Why a local agent's docs links broke, and the fix
An agent names the knowledge base hm://hyper.media, but that name means three different spaces (production, staging, a checkout's hm-sync dev site). A local agent's links opened the production docs instead of the dev site it had read. The agents server now tells the model the space it reads and resolves the links it writes. Three short videos explain it.

On 2026-11-17 Hazel, an agent running on Yacht's local app server, was asked for links to the documentation on apps, triggers and pages. It read the right pages and answered with four links. Three of them opened "not found". This note explains why, what was changed, and what is still open.

The fix is seed#1388 (open, CI green as of 2026-11-17). Three short videos below walk through it; each section also has the detail in text.

The short version

    The knowledge base is the hypermedia/ folder of the Seed repo. Agents are told it lives at hm://hyper.media.

    That folder is published into three spaces, each a different account: production (from tagged releases), staging (every merge to main), and a dev site per checkout (the ./dev hm-sync loop).

    An agents server is configured with one of them and swaps that account in when an agent reads hm://hyper.media/…. Nothing swapped it in when the agent wrote a link.

    A client that opens hm://hyper.media/… asks who owns the hyper.media domain, which is always the production space. So a dev or staging agent's links opened production, where pages changed since the last release are missing.

    Fix: the server tells the model the account it reads, and resolves any link destination that still names hm://hyper.media before a reply is stored or a document or comment is published.

1. One name, three spaces

Space

Account

Published

Read by

Production

z6MkfzKMhF9k1oPaQsShWAg8xJzbWf5kaZgn1MkeZvhcAsmB

only from a tagged release (sync-hypermedia.yml, target production)

production app servers; anyone resolving the hyper.media domain

Staging

z6MkkW8Uh77G79XMED3KLFiSqoYMqSF63fJMLEiYBNpF9xnL

every merge to main that touches hypermedia/

staging

Dev

one key per checkout; on Yacht z6Mkpgw8sbZjmrhaUjtBLuhd5d3MAi3Khr7EN4QntzWdT55r

live, by ./dev hm-sync hypermedia

the local app server

The dev loop writes its account to hypermedia/.dev/account. The local app server is started with SEED_APPS_DOCS_ACCOUNT_FILE pointing at that file and reads it on every use, so a new dev key needs no restart. Deployed servers get the account from SEED_AGENTS_DOCS_ACCOUNT.

The swap from hm://hyper.media to the configured account lives in apps/src/docs-space.ts. Before this change it was applied in three places: the read verb, embeds in an agent's prompt (the default Agent Guide), and the default prompt URL the server reports to clients.

2. How the links broke

What the session log shows (session 5c347152-bc1b-4b44-a941-4d53d016829e on Yacht's local server):

    Hazel read hm://z6Mkpgw8…/app-environment/tools (the dev site) and the write guides for apps, pages and triggers. Every read succeeded.

    Its reply linked hm://hyper.media/app-environment/tool-document, hm://hyper.media/app-environment/triggers, hm://hyper.media/apps/document-pages and hm://hyper.media/app-environment/tools. The system prompt said "The Hypermedia knowledge base is at hm://hyper.media", so the model wrote links in that form.

    The reply was stored as written.

    The app opens an hm://<domain>/… link by resolving the domain (resolveDomainHmUrl, GetDomain). hyper.media is registered to the production docs account.

    Production was last published from a release in which these pages lived under /agent/…. The /app-environment/… paths exist on the dev site and on staging, not yet in production.

Link in the reply

Dev site

Production

/app-environment/tool-document

found

not found

/app-environment/triggers

found

not found

/app-environment/tools

found

not found

/apps/document-pages

found

found

The paths were right. The space was wrong. The same would happen to a staging agent, and to a production agent whenever a link's meaning should follow the server's configured account instead of the domain.

flowchart LR A[Agent prompt: knowledge base is hm://hyper.media] --> B[read hm://hyper.media/x] B -->|server swaps in its account| C[Dev site page] A --> D["reply: [x](hm://hyper.media/x)"] D -->|stored as written| E[Client opens link] E -->|resolves the hyper.media domain| F[Production space: page missing]

3. The fix

Two changes in the agents server, plus the docs that describe them.

The prompt names the space the server reads. seedAssistantSystemPrompt takes a knowledgeBaseUrl, and the server passes hm://<configured account>. Where the embedded Agent Guide names the knowledge base root (hm://hyper.media), the server substitutes the account too. This is resolved on every turn, after the prompt cache, so a changed dev key is picked up. The model now sees one address for the knowledge base: the one its reads return.

Link destinations are resolved when the agent writes. resolveDocsMarkdown rewrites [text](hm://hyper.media/…) and <hm://hyper.media/…> to the configured account:

    in an assistant reply, before it is stored in the session log;

    in a document the agent publishes (parseMarkdownOrBadRequest);

    in a comment the agent posts.

What is left alone. Fenced code, inline code and plain prose. hm://hyper.media/struct, hm://hyper.media/app and the like are library type names, and metadata.type must keep them literally.

With no account configured, nothing changes.

What is still open

    Replies stored before the fix keep their hm://hyper.media links. Ask the agent again.

    While a reply streams, the text shows what the model wrote. The stored message has the resolved link.

    A dev key change leaves earlier replies pointing at the previous dev account. The dev loop tombstones retired dev sites, so those links stop opening.

    A bare hm://hyper.media/… URL in prose is not rewritten, because it cannot be told apart from a type name. The prompt asks for Markdown links and now names the account, so this should be rare.

    Production lags main by a release. That is by design, but it means the hyper.media domain is the wrong target for anything written against main. Anything else that hands a model or a user an hm://hyper.media/<page> address has the same problem.

    Other tool inputs. Only read accepts the alias. query, search and attributes scoped to hm://hyper.media/… are not resolved. With the model given the account, it has no reason to use the alias there.

How it was checked

    Unit tests for the new functions in apps/src/docs-space.test.ts; the whole apps/ suite passes (844 tests).

    node scripts/hypermedia/check.mjs, pnpm format:check and pnpm typecheck pass.

    Each link was fetched from the dev site and from production to build the table above.

    Not done: a fresh live session on the patched server to see a corrected reply end to end.

Do you like what you are reading? Subscribe to receive updates.

Unsubscribe anytime