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 |
| only from a tagged release ( | production app servers; anyone resolving the |
Staging |
| every merge to main that touches | staging |
Dev | one key per checkout; on Yacht | live, by | 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 |
|---|---|---|
| found | not found |
| found | not found |
| found | not found |
| 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