# AzrvanAkaranA — AI reading and browser operation

This is a personal website with nine public collections. The human interface,
Markdown snapshots and browser tools use the same catalogue and translations.

## Discovery

- `llms.txt` lists every page and its English, Russian, Estonian and German Markdown versions.
- Each HTML document links to its Markdown versions with `rel="alternate"`,
  `type="text/markdown"` and `hreflang`. It also links to this guide, `llms.txt`
  and `webmcp-tools.json`.
- `webmcp-tools.json` is a descriptive catalogue of the live tools and their JSON
  input schemas. It is not an HTTP MCP server or a tool-execution endpoint.
- Markdown filenames: `index.md`, `reading.md`, `horror.md`, etc. English has no
  language suffix; other versions use `.ru.md`, `.et.md` or `.de.md`.
- Markdown snapshots contain the complete unfiltered page. Live tool results
  reflect the current browser language, query, scope and filter.

All paths are relative to the deployed site directory, including when hosted
under a subdirectory. Normal HTML documents also contain the public collection
content without JavaScript. Interface operations use the live Vue application.

## WebMCP browser API

The site feature-detects the current [WebMCP draft API](https://webmachinelearning.github.io/webmcp/),
`document.modelContext.registerTool()`, and supports older browser previews using
`navigator.modelContext.registerTool()`. WebMCP is an evolving browser feature;
the site does not install a polyfill or require a browser extension.

In a supporting secure browser context, the document registers six tools. With
the current draft API, an in-page agent can discover and execute them:

```js
const tools = await document.modelContext.getTools()
const navigate = tools.find(tool => tool.name === 'navigate_site')
const result = JSON.parse(await document.modelContext.executeTool(navigate, {
  page: 'horror'
}))
```

Browser-integrated agents may provide their own native discovery and invocation
interface. Earlier previews have different discovery APIs; use the browser's
available WebMCP interface rather than assuming `getTools()` exists there.
Tools remain registered through SPA navigation and language switches. Registration
uses an abort signal for lifecycle cleanup; earlier previews with `unregisterTool()`
are supported as well. No cross-origin tool exposure is requested.

## Tools

Every tool accepts a JSON object and returns a JSON-serializable object:

```json
{ "ok": true, "result": {} }
```

Validation or unavailable-operation errors return:

```json
{ "ok": false, "error": "Description of the problem and how to recover." }
```

Arguments are validated in the site, including enums, integer ranges and unknown
fields. Collection reads support `offset` (zero-based, default 0) and `limit`
(1–100, default 20), returning `total`, `entries` and `nextOffset`.

### `get_site_info({})`

Read the current page, language, theme, theme lock, page/document URLs and active
collection controls. Its `collection.filters` and `collection.scopes` list the
current valid values. This tool is read-only.

### `navigate_site({ page, section? })`

Open `home`, `wheel`, `horror`, `reading`, `music`, `videos`, `cooking`, `science`,
`epub` or `fungi` in the visible page. Tool results wait for the asynchronous view.
Existing route query parameters are retained. For the Wheel article, an optional
`section` is one of the heading IDs returned by `read_collection`.

### `read_collection({ entryId?, offset?, limit? })`

Read the current collection without changing the UI. Results contain plain text,
stable IDs and usable absolute resource links. A specific `entryId` returns a
matching entry from the current visible results.

- Horror listings return author group IDs, original/display names, listed aliases,
  research status and matching work counts. Reading a specific author returns its
  paginated works, one-based work indices, original/listed titles, source URLs,
  publication metadata, provisional-translation status and attribution notes.
- Recipes include ingredients, preparation and stable category IDs.
- Downloads include resource URLs, formats and byte sizes.
- The Wheel returns article sections with IDs, titles and text. A section ID can
  also be passed as `entryId` to read a particular section.

This tool is read-only. If a requested entry is hidden, change or clear the
current query/filter with `search_collection` first.

### `search_collection({ query, filter?, scope?, offset?, limit? })`

Set the current collection's search text (maximum 500 characters) and optional
filter/scope, then return matching results. The visible search field and results
update together. An empty query clears the search. `filter: "all"` clears a
filter; valid filter values come from `get_site_info`.

Horror `scope` is `all`, `authors` or `works`. Both original-language names/titles
and the original listed aliases are searchable. Recipe and reading filter values
are stable across interface languages. The Wheel article has no collection search.

### `set_site_preferences({ language?, theme? })`

Set at least one preference. `language` is `en`, `ru`, `et` or `de`; `theme` is
`light` or `dark`. These use the header controls' saved preferences and preserve
the route, search, filters and open source panels. The Wheel is permanently dark:
its theme setting is unavailable until navigating to another page.

### `set_horror_sources({ authorId, workIndex?, expanded })`

Expand or collapse a visible horror bibliography panel. Omit `workIndex` for an
author's identity evidence, or provide the one-based work index for its title and
publication evidence. `expanded` is a boolean. The same arrow button and source
panel update in the human interface. A hidden entry needs an appropriate search
first.

## Example workflow

```text
navigate_site({"page":"horror"})
search_collection({"query":"Аксаков","scope":"authors"})
read_collection({"entryId":1,"offset":0,"limit":20})
set_horror_sources({"authorId":1,"workIndex":1,"expanded":true})
set_site_preferences({"language":"et"})
```

For the Wheel, read section IDs, then navigate to the selected heading. For a
download, read its resource URL and use the browser's normal link/download
behavior. The tools return resource links without starting downloads automatically.

## HTML and automation fallback

Without WebMCP, the same actions are available through semantic HTML:

- `main#main-content[data-page]` identifies the active page and reports loading
  through `aria-busy`.
- A labelled `form[role="search"]` contains `input#collection-search[name="query"]`.
  Search updates immediately; Enter does not navigate away.
- `select#collection-filter[name="filter"]` and horror
  `select#search-scope[name="scope"]` expose stable option values.
- `.language-switch button[lang]` and `.theme-switch button` change preferences;
  theme buttons use localized accessible names.
- Horror `.author-section[data-author-id]` contains
  `.horror-works > li[data-work-index]`. Each arrow button has a contextual
  accessible name, `aria-expanded`, and an open panel's `aria-controls` reference.
- Other list/card/table entries expose `data-entry-id` where applicable.
- Article headings have stable `wheel-section-*` IDs. Download links have real
  `href` values and a `download` attribute. Poster links expose original images.

## Bibliography and content conventions

Verified horror originals retain their original language in every interface.
Italic unresolved titles are provisional AI translations, not verified originals.
Publication countries and dates are verified independently; an absent value means
not established, not a negative finding. Country flags describe first original-
language publication places, not author nationality. Historical states and
version/attribution disputes are recorded in evidence. Dates of composition and
translated editions are not substituted for first publication. Duplicates and
source author/work associations are retained.

The site has no account, checkout, editing or catalogue-mutation tools. Browser
preferences and visible navigation/search/disclosure state are the supported
changes. Tool responses and Markdown describe public site content; cited external
links remain bibliographic references.