Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

prompts(finish): file orders 406 and 407 from a live audit:docs measurement

nirholas6bb307ce2180
diff --git a/prompts/finish/406-auto-fix-stranded-prompt-links.md b/prompts/finish/406-auto-fix-stranded-prompt-links.md
new file mode 100644
index 000000000..d62845aa3
--- /dev/null
+++ b/prompts/finish/406-auto-fix-stranded-prompt-links.md
@@ -0,0 +1,141 @@
+# 406. Fix dead links left behind by retired work orders, found by `audit:docs`
+
+How to run: paste this file's repo path into a fresh Claude Code chat in this repository and
+say "run this work order". Runnable now, no gate. Written by the evolve scout lane on
+2026-10-14 from a live `npm run audit:docs` run.
+
+## Operating clause (binding)
+
+- Read CLAUDE.md first. CLAUDE.md overrides everything, including this file.
+- Finish 100% in this session. Never end the turn with a question, an option list, or an
+ unexecuted plan. A judgment call goes in one line of the final report; it never becomes a
+ question that halts work.
+- The only permitted stops are the CLAUDE.md stop-and-ask gates: spending real funds or any
+ irreversible on-chain write, `git push` or a production deploy, posting to an external
+ channel, committing content that names a crypto project other than $THREE, and destroying
+ unrecoverable data. This order touches none of them.
+- No mocks, no TODO markers, no commented-out code, no stub functions. These are prose/doc
+ fixes; every link you touch must resolve to something real, not a placeholder.
+- The em-dash and en-dash characters are banned in everything you write.
+- Concurrent agents share this worktree: stage explicit paths only (never `git add -A` or
+ `git add .`), re-check `git status` and `git diff --staged` before each commit.
+- Before committing, run `npm run check:rules -- --paths <files you touched>`. It must exit 0.
+
+## Why this matters (measured 2026-10-14)
+
+`npm run audit:docs` fails today with, among other findings, these dead relative links:
+
+```
+docs/partners/outreach-plan.md:82 ../../prompts/finish/072-best3d-06-engine-bridges.md
+docs/partners/outreach-plan.md:85 ../../prompts/finish/075-best3d-09-three-vrm.md
+docs/partners/prospects.md:82 ../../prompts/finish/075-best3d-09-three-vrm.md
+docs/partners/prospects.md:100 ../../prompts/finish/075-best3d-09-three-vrm.md
+docs/partners/tripo.md:142 ../../prompts/finish/084-partners-01-tripo-v3-house-lane.md
+apps/hq/README.md:50 CLAUDE.md
+apps/hq/docs/DOCUMENTATION.md:3476 ROADMAP.md
+apps/hq/docs/DOCUMENTATION.md:3529 ROADMAP.md
+apps/hq/docs/deploy-cloud-run.md:52 ../.env.example
+```
+
+All three `prompts/finish/*.md` targets are gone because the orders they named shipped and
+were retired in their own closing commits:
+
+- `072-best3d-06-engine-bridges.md`: retired by `f60c5e0a7` ("engine bridges shipped and
+ verified").
+- `075-best3d-09-three-vrm.md`: retired by `91d2a3779` ("real three-vrm integration shipped
+ and verified").
+- `084-partners-01-tripo-v3-house-lane.md`: retired by `a196023fb` ("Tripo v3 house lane
+ shipped and verified").
+
+This is exactly the failure mode `prompts/README.md`'s "Runtime consumption" section warns
+about: "Before retiring a prompt file, grep for inbound references and rewrite them to name
+the campaign + work order instead of the path." That step was skipped for these three
+retirements, so three partner-facing planning docs now send a reader into a 404 on GitHub (the
+path no longer exists) instead of to the shipped feature.
+
+The `apps/hq` findings are a second, unrelated class in the same audit run: that workspace
+app's own README and docs reference `CLAUDE.md` and `ROADMAP.md` files that were never created
+in `apps/hq/`, and its deploy doc references a `.env.example` one level up that also does not
+exist.
+
+Not in scope, verified as false positives this session, do not "fix" them:
+
+- `hubs/awesome-agent-identity/README.md:23`, `hubs/awesome-agent-protocols/README.md:11`,
+ `hubs/awesome-solana-agents/README.md:7`: each links `../../issues/new?template=...`. These
+ `hubs/` directories are curated lists meant to become standalone GitHub repos (see
+ `prompts/README.md`'s promotion-path pattern); the relative link is correct for that future
+ repo's own root and only "breaks" inside this monorepo, which has no `issues/` directory.
+ Confirm this reading holds (`ls hubs/*/`, check for a repo-promotion note) and leave these
+ alone.
+- `docs/research/oss-landscape-2026-10-notes/chat-memory-evals.md:3` links an absolute local
+ path (`/home/user/projects/three.ws/packages/agent-memory/README.md`). Decide whether to
+ make it relative (`../../../packages/agent-memory/README.md`, verify the target exists first)
+ while you are in this file class, since it is the same audit run and the same fix shape
+ (dead/wrong link), but it is lower priority than the three retired-order links above.
+
+A stray local-only directory this session found and removed, not a repo issue, no action
+needed: `workers/model-triposplat/` held nothing but a gitignored `__pycache__/` (confirmed
+with `git ls-files workers/model-triposplat`, empty) and caused a false "directory needs a
+README" audit finding; it no longer exists on disk in this worktree. If `npm run audit:docs`
+still reports it, it has been recreated by something else since this measurement; re-check
+before treating it as a real gap.
+
+## Tasks
+
+1. **Fix the three retired-order links.** For each of the three files above, read the
+ surrounding paragraph the dead link sits in, then replace the link with prose naming what
+ shipped (use the retiring commit's subject line as the fact, not the deleted path). Do not
+ link to a commit SHA as a substitute; name the shipped feature and, where one exists, a
+ live doc or page that covers it (e.g. three-vrm's shipped state likely has a doc under
+ `docs/`; engine bridges and the Tripo v3 house lane likewise; search `git show <sha> --stat`
+ for each retiring commit to find what doc, if any, it shipped alongside, and link that
+ instead of leaving prose with no link at all).
+ - `docs/partners/outreach-plan.md` lines 82 and 85
+ - `docs/partners/prospects.md` lines 82 and 100
+ - `docs/partners/tripo.md` line 142
+2. **Fix the `apps/hq` links.** Read `apps/hq/README.md:50` and `apps/hq/docs/DOCUMENTATION.md`
+ around lines 3476 and 3529 to see what a contributor guide (`CLAUDE.md`) and a roadmap
+ (`ROADMAP.md`) for that app would need to say. Either write minimal real files at
+ `apps/hq/CLAUDE.md` and `apps/hq/ROADMAP.md` (if the content is substantial enough that a
+ contributor genuinely needs it and it does not already live elsewhere in `apps/hq/docs/`),
+ or repoint the links at the doc that already carries this content (check
+ `apps/hq/docs/DOCUMENTATION.md` itself first; it may already be the de facto contributor
+ guide and roadmap, in which case the two links should point there instead of to files that
+ were never created). For `apps/hq/docs/deploy-cloud-run.md:52`, check whether
+ `apps/hq/.env.example` should exist (compare against the root `.env.example` and whatever
+ env vars `apps/hq`'s own code reads) and either create it or repoint the link at the correct
+ existing example file.
+3. **Re-run the audit.** `npm run audit:docs` must report zero findings for every link this
+ order touched. Findings this order explicitly left alone (the three `hubs/` links) are
+ allowed to remain, but confirm they are the *only* remaining findings before calling this
+ done, since a fresh regression elsewhere would mean something else changed the file set
+ mid-session.
+
+## Definition of done
+
+- [ ] `npm run audit:docs` no longer lists the nine links named above as dead (the three
+ `hubs/` links may remain; nothing else may).
+- [ ] Every rewritten link resolves to a real file or a real, live URL; no link points at a
+ path that does not exist.
+- [ ] No placeholder text ("TBD", "coming soon", a bare commit SHA with no explanation) stands
+ in for a real fix.
+- [ ] `npm run check:rules -- --paths <files you touched>` exits 0.
+- [ ] `git status` shows nothing stray left uncommitted that this order created.
+- [ ] Explicit-path commit(s), one topical commit per class of fix (the three partner docs as
+ one commit, the `apps/hq` fixes as another, since they are unrelated causes).
+
+## Never blocked (pre-answered)
+
+| Blocker | Do this |
+|---|---|
+| Can't tell what the three.vrm/engine-bridges/tripo work shipped | `git show <retiring-sha> --stat` lists every file that commit's retirement touched; `git log --all --oneline --grep "three-vrm"` (or the relevant keyword) across the whole history finds the feature commit itself, usually just before the retirement commit. |
+| `apps/hq/docs/DOCUMENTATION.md` is too large to read in one pass | It is a single large generated-style doc; use `grep -n` for the sections around the two line numbers given, plus a search for existing "Contributing" or "Roadmap" headings before deciding whether to write new files or repoint links. |
+| A link fix would need content naming a crypto project other than $THREE | Everything touched here is three.ws's own partner planning and an internal app's contributor docs; if a specific sentence genuinely needs another project's name to stay truthful, leave that one hunk uncommitted and say so in the report, but commit everything else. |
+| `workers/model-triposplat/` exists again when you check | Confirm with `git ls-files workers/model-triposplat`; if it is still untracked `__pycache__` only, delete it the same way this session did and note it in the report rather than writing docs for it. |
+
+## Report format
+
+1. The `audit:docs` output before and after, side by side.
+2. What each of the nine fixed links now points at and why.
+3. Confirmation the three `hubs/` links are the only findings left, or an explanation if not.
+4. Commit SHAs.
diff --git a/prompts/finish/407-auto-publish-orphaned-docs.md b/prompts/finish/407-auto-publish-orphaned-docs.md
new file mode 100644
index 000000000..3509ff857
--- /dev/null
+++ b/prompts/finish/407-auto-publish-orphaned-docs.md
@@ -0,0 +1,155 @@
+# 407. Publish or explicitly park the 10 docs pages that are live but undiscoverable
+
+How to run: paste this file's repo path into a fresh Claude Code chat in this repository and
+say "run this work order". Runnable now, no gate. Written by the evolve scout lane on
+2026-10-14 from a live `npm run audit:docs` run.
+
+## Operating clause (binding)
+
+- Read CLAUDE.md first. CLAUDE.md overrides everything, including this file.
+- Finish 100% in this session. Never end the turn with a question, an option list, or an
+ unexecuted plan. A judgment call on any one doc goes in one line of the final report; it
+ never becomes a question that halts work on the other nine.
+- The only permitted stops are the CLAUDE.md stop-and-ask gates: spending real funds or any
+ irreversible on-chain write, `git push` or a production deploy, posting to an external
+ channel, committing content that names a crypto project other than $THREE, and destroying
+ unrecoverable data. This order touches none of them.
+- No mocks, no TODO markers, no placeholder descriptions. A `data/pages.json` entry you add
+ must carry a real, accurate title and description of the doc's actual content.
+- The em-dash and en-dash characters are banned in everything you write.
+- Concurrent agents share this worktree: stage explicit paths only (never `git add -A` or
+ `git add .`), re-check `git status` and `git diff --staged` before each commit.
+- Before committing, run `npm run check:rules -- --paths <files you touched>` and
+ `npm run audit:docs`. Both must exit 0 (or report only pre-existing, unrelated findings).
+
+## Why this matters (measured 2026-10-14)
+
+`npm run audit:docs` reports 10 docs served live at `/docs/<slug>` that no crawler, sitemap,
+or `llms.txt` entry can find, because they carry no entry in `data/pages.json` and no entry in
+the script's own `UNPUBLISHED_DOCS` exemption list (`scripts/audit-docs.mjs:284`):
+
+```
+docs/forge-workflows.md
+docs/listings-registry.md
+docs/run-receipts-x-reply-and-thread.md
+docs/standalone-repo-playbook.md
+docs/standalone-repos.md
+docs/team-chat.md
+docs/ui-lint.md
+docs/x-mention-avatar.md
+docs/x-partner-series.md
+docs/x-reply-playbook.md
+```
+
+A doc in this state is the worst of both worlds: it answers 200 to anyone who finds the exact
+URL, so it is not actually private, but it is in no sitemap and no nav, so almost nobody does.
+Each one needs exactly one of two outcomes: a real `data/pages.json` entry (if it documents a
+live, user-facing feature) or an entry in `UNPUBLISHED_DOCS` with the reason (if it is
+genuinely internal, a dry-run operator note, or gated behind something not yet live), per the
+rule at the top of `scripts/audit-docs.mjs`. This session's own research into each file,
+to save the next agent from re-deriving it:
+
+- **`forge-workflows.md`** documents a real, live app route: `/forge/workflows` is already in
+ `data/pages.json` (confirmed at `data/pages.json:875`). The doc itself says "Page:
+ [/forge/workflows](https://three.ws/forge/workflows)". This is a straightforward miss: add
+ the doc page entry alongside the existing app-route entry.
+- **`team-chat.md`** is the same shape: `/team-chat` is already a live route in
+ `data/pages.json` (confirmed at `data/pages.json:2181`), and the doc documents that feature
+ ("Squad chat is the conversational front door to your agents"). Add the doc entry.
+- **`run-receipts-x-reply-and-thread.md`** opens with "Nothing here is posted or queued" and
+ "Every link to `/runs` needs the next production deploy before it resolves." This is an
+ internal drafting note for a not-yet-live X reply, the same category as the existing
+ `UNPUBLISHED_DOCS` entries for `x-mention-bot` and `x-mention-image3d`. Add it to
+ `UNPUBLISHED_DOCS` with that reason; re-check at publish time whether it should move to
+ `data/pages.json` once the run is live.
+- **`x-mention-avatar.md`** documents the `avatar` intent of the X mention bot and says
+ explicitly "It runs in dry run only... nothing is posted to X until the account goes live."
+ This is a sibling of the two X-mention-bot entries already in `UNPUBLISHED_DOCS`
+ (`x-mention-bot`, `x-mention-image3d`) that were simply missed when those were added. Add it
+ with the same "public once the bot goes live" framing.
+- **`x-partner-series.md`** and **`x-reply-playbook.md`** are both internal X content
+ operating playbooks (the daily partner spotlight format, and the long-thread-plus-article
+ recipe for answering questions), the same category as the existing `UNPUBLISHED_DOCS`
+ entries `announcement-coverage`, `announcement-coverage-telegram`, and
+ `announcement-factory` ("internal: the marketing machinery that fills the X content queue").
+ Add both with an equivalent reason.
+- **`ui-lint.md`** documents an internal dev tool (`lintapple`, a design-system QA script run
+ against `ui-policy.json`), not a reader-facing product feature. Add it to
+ `UNPUBLISHED_DOCS` as internal tooling documentation.
+- **`standalone-repo-playbook.md`** is an internal checklist for making a package discoverable
+ by humans and LLM crawlers once mirrored out of this monorepo; it is written for whoever
+ runs the mirror-promotion work, not for an end user. Add it to `UNPUBLISHED_DOCS` as
+ internal.
+- **`listings-registry.md`** and **`standalone-repos.md`** are the two genuinely ambiguous
+ ones; this session did not find an existing public page that already surfaces either, so
+ resolve them fresh:
+ - `listings-registry.md` is a generated master index ("Every place three.ws is listed,
+ submitted to, or known to be absent from") built by `scripts/listings.mjs` from
+ `data/listings.json`, distinct from the prose doc `docs/listings.md` it cross-links.
+ Check whether `docs/listings.md` itself is in `data/pages.json`; if it is and is treated as
+ the public-facing version, `listings-registry.md` is probably the internal operator
+ tracker and belongs in `UNPUBLISHED_DOCS`. If neither is published, decide based on
+ whether the content (a registry of submission statuses, some likely showing "absent from")
+ is something three.ws wants a competitor or partner reading verbatim; when in doubt,
+ `UNPUBLISHED_DOCS` is the safer default and this order's own binding clause says a
+ judgment call here is a one-line report note, not a reason to stop.
+ - `standalone-repos.md` is a generated catalog ("Every publishable package in this monorepo
+ is mirrored to its own repository... so it can be found, starred, installed and cited on
+ its own") from `scripts/gen-standalone-catalog.mjs`. This reads as exactly the kind of page
+ three.ws wants discoverable (it is marketing the open-source footprint), and `/open-source`
+ already exists as a related live page per `data/pages.json:59`. Check whether
+ `/open-source` already renders this catalog's content; if it does not, this is the
+ strongest "publish it" candidate of the ambiguous pair, since it directly supports the
+ existing open-source-credits and open-source-engine docs already live nearby in
+ `data/pages.json` (see the entries around lines 496, 852, 869, 909 for the pattern and
+ phrasing to match).
+
+## Tasks
+
+1. For `forge-workflows` and `team-chat`: add a doc-page entry to `data/pages.json` using the
+ same shape as a neighboring doc entry (title, path `/docs/<slug>`, description written from
+ the doc's actual first paragraph, not a placeholder).
+2. For `run-receipts-x-reply-and-thread`, `x-mention-avatar`, `x-partner-series`,
+ `x-reply-playbook`, `ui-lint`, `standalone-repo-playbook`: add each to `UNPUBLISHED_DOCS`
+ in `scripts/audit-docs.mjs` (around line 284) with a one-line reason in the house style of
+ the existing entries there.
+3. For `listings-registry` and `standalone-repos`: do the research named above (grep
+ `data/pages.json` for `/open-source` and `docs/listings.md`, read what each currently
+ renders), make the call, and either publish (task 1's shape) or park (task 2's shape).
+4. Run `node scripts/build-pages.mjs` or whatever `npm run build:pages` wraps if you touch
+ `data/pages.json`, so any derived sitemap/llms.txt artifact regenerates in the same commit
+ rather than drifting from the source table.
+5. Append one `data/changelog.json` entry covering whichever docs actually got published in
+ task 1 and task 3 (not the `UNPUBLISHED_DOCS` ones, since those stay invisible by design).
+
+## Definition of done
+
+- [ ] `npm run audit:docs` no longer lists any of the 10 slugs above under "Public docs missing
+ from data/pages.json".
+- [ ] Every `data/pages.json` entry added has a real title and a description quoting or
+ accurately summarizing the doc's actual content, not a generic placeholder.
+- [ ] Every `UNPUBLISHED_DOCS` entry added has a reason in the same one-line house style as its
+ neighbors, not just "internal".
+- [ ] If `data/pages.json` changed, the derived build output (sitemap/llms.txt, via
+ `npm run build:pages`) was regenerated in the same commit.
+- [ ] `data/changelog.json` has one new entry for whichever docs were newly published (skip
+ this line entirely if every one of the 10 ended up in `UNPUBLISHED_DOCS`, since nothing
+ user-visible changed).
+- [ ] `npm run check:rules -- --paths <files you touched>` exits 0.
+- [ ] Explicit-path commit(s).
+
+## Never blocked (pre-answered)
+
+| Blocker | Do this |
+|---|---|
+| Can't tell if `/open-source` already renders the standalone-repos catalog | Read `src/*.js` or the page template behind `/open-source` (grep `data/pages.json:59`'s neighboring route wiring) directly; if it already shows an equivalent table, `standalone-repos.md` is redundant prose and belongs in `UNPUBLISHED_DOCS` instead of being published a second way. State which you found. |
+| `npm run build:pages` doesn't exist under that exact name | Check `package.json` for the actual script name (`grep -n "build:pages\|build:sitemap\|build:llms" package.json`); run whichever one regenerates the artifacts `data/pages.json` feeds. |
+| A doc's true intent is still ambiguous after the research above | Default to `UNPUBLISHED_DOCS` (the reversible, lower-risk choice: a doc can be promoted to `data/pages.json` any time with no data loss, while publishing something meant to stay internal is harder to fully undo once crawled). State the call and move on; this is exactly the kind of judgment call the binding clause says goes in one report line, not a stop. |
+
+## Report format
+
+1. The `audit:docs` "Public docs missing" section before and after.
+2. A table: slug → outcome (published to `data/pages.json` / parked in `UNPUBLISHED_DOCS`) →
+ one-line reason.
+3. Whether `data/pages.json`-derived build output was regenerated, and how you verified it.
+4. Commit SHA(s).