docs: split integration docs and restore docs mode

[PipDscvr]

Summary

• split each integration into overview, local, and cloud docs
• restore the production-vs-source docs mode flag for self-managed local pages
• simplify integration setup docs around automatic service/auth resolution and session-based default identity
• keep the combined logo/wordmark navbar treatment and anchor-heading UX changes on this branch

Validation

• npm run typecheck
• npx docusaurus build --out-dir /private/tmp/atomicmemory-docs-build-source
• ATOMICMEMORY_DOCS_MODE=published npx docusaurus build --out-dir /private/tmp/atomicmemory-docs-build-published

[ethanj]

Review of PR #4 (docs: split integration docs and restore docs mode)

The integration docs split (overview / local / cloud per integration) is a good restructure, the new DocsMode flag is clean, and the slug strategy (slug: /integrations/coding-agents/claude-code/local) keeps URLs stable. But the PR ships three regressions against AFDocs work merged in PR #5 that will break the live build and degrade the agent-facing markdown — these need to land before merge.

I checked out the branch (6a97c0b), ran npm install, then npm run build.

---

🔴 Blocker 1 — AFDocs runtime deps removed from package.json

6a97c0b deletes cheerio, turndown, turndown-plugin-gfm, js-yaml, @types/js-yaml, and @types/turndown from devDependencies. Those are required by scripts/mirror-markdown.mjs (added in PR #5 to render the .md mirror from built HTML for AFDocs markdown-content-parity).

$ npm run build
[ERROR] Error: Docusaurus could not load module at path
  ".../src/plugins/llms-and-mirror-plugin.mjs"
  [cause]: Error: Cannot find module 'turndown'
  Require stack:
  - .../scripts/mirror-markdown.mjs

Fix: keep all six entries in devDependencies from origin/main's package.json. The package-lock.json should also retain them.

I suspect the deps got dropped during a package.json formatting/dedupe pass alongside the version bumps to ^3.10.1 — easy to drop accidentally.

---

🔴 Blocker 2 — prebuild / prestart auto-regen reintroduced

6a97c0b adds back:

"write:docs-mode": "node scripts/write-docs-mode.mjs",
"prestart": "npm run write:docs-mode && npm run regen:api",
"prebuild": "npm run write:docs-mode && npm run regen:api",

PR #5 explicitly removed the prebuild/prestart auto-regen of regen:api (commit 08c5312) because it dirtied 29 committed .api.mdx files on every build (non-deterministic re-encoding of the compressed api: blob). I just reproduced that regression on this branch:

$ git status -sb
 M docs/api-reference/http/consolidate-memories.api.mdx
 M docs/api-reference/http/ingest-memory-quick.api.mdx
 M docs/api-reference/http/ingest-memory.api.mdx
 M docs/api-reference/http/search-memories-fast.api.mdx
 M docs/api-reference/http/search-memories.api.mdx
 M docs/api-reference/http/update-config.api.mdx

Fix: keep write:docs-mode as a script (it's needed) but stop calling regen:api from prebuild / prestart. Two clean options:

"prestart": "npm run write:docs-mode",
"prebuild": "npm run write:docs-mode",

…or fold write:docs-mode directly into start / build if you want a single-call shape. Either way: don't run regen:api automatically. Spec refresh stays the explicit npm run vendor:spec && npm run regen:api && commit flow that scripts/vendor-core-spec.mjs:14 already documents.

---

🔴 Blocker 3 — src/theme/Heading swizzle breaks .md mirrors

The new <Heading> component wraps every heading's text in an anchor link with a # icon span. Rendered HTML:

<h1 class="anchor anchorTarget_QU3I" id=observability>
  <a href=#observability class=headingLink_no4V title="Copy link to Observability">
    <span aria-hidden=true class=headingIcon_Pk3T>#</span>
    <span class=headingText_IKAy>Observability</span>
  </a>
</h1>

scripts/mirror-markdown.mjs reads each route's HTML, strips known chrome (breadcrumbs, TOC, copy buttons, a.hash-link) before turndown, then converts to markdown. scripts/mirror-markdown.mjs:147-159 strips a.hash-link, but the new component uses CSS-module class names (headingLink_no4V, headingIcon_Pk3T) — different class, same purpose. So turndown converts the whole anchor + icon as part of the heading text:

$ head -2 build/platform/observability.md
# [#Observability](#observability "Copy link to Observability")

Every heading on every hand-authored page now reads that way. AFDocs's markdown-content-parity check tolerates this (HTML and md both render the link), but agents reading the mirror see broken-looking headings with a stray # glued to the title text. It also pushes the H1 text past where the remark plugin's directive injection looks for it (the plugin matches node.type === 'heading' && depth === 1 on the AST, so injection still works at parse time — but anything that operates on the rendered .md will see noise).

Fix: in src/theme/Heading/index.tsx, either:

1. Add data-markdown-ignore to the icon span (AFDocs strips it before parity comparison; my mirror could also use it as a strip selector), or
2. Add the hash-link class to the wrapping <a> (compat with default Docusaurus selectors that other tooling assumes), or
3. Render the icon span via CSS pseudo-element (::before) so it's never in the DOM text content.

Option 3 is cleanest — keeps the hover affordance, drops the # from the converted text, doesn't require mirror-markdown.mjs changes.

If you'd rather keep the JSX structure, add the icon class to the noise selector list:

// scripts/mirror-markdown.mjs:146
const ARTICLE_NOISE_SELECTORS = [
  …,
  "a.hash-link",
  "[class*='headingIcon']",          // ← add
  "[class*='headingLink']",          // ← also strip the wrapping link
  …
];

…and update the findInsertIndex / heading conversion in turndown to keep just the headingText span content. That works but couples the mirror to theme internals.

---

🟡 Concern 4 — collision with PR #6 (round 3)

PR #6 (open at #6) is the round-3 AFDocs follow-up:

• Adds the Agent index: [llms.txt](/llms.txt) directive to OpenAPI mirrors
• Drops .well-known/mcp.json from llms.txt's "Optional" section

It touches scripts/build-llms-txt.mjs and scripts/mirror-markdown.mjs — both files PR #4 also modifies (for blocker 1's revert). Whichever PR merges second will need a small rebase. No deep conflict, just heads-up.

---

🟡 Concern 5 — <PublishedOnly> / <SourceOnly> interaction with markdown mirrors

The mirror reads built HTML, so it captures only the active ATOMICMEMORY_DOCS_MODE's branch. If you build with ATOMICMEMORY_DOCS_MODE=published, the .md mirror has only published content; if you build with source, it has only source content. That's probably fine — we want the mirror to match what users see — but worth being explicit:

• The published deploy at docs.atomicmemory.ai decides which branch shows up in the mirror.
• If you ever ship two deploys (one published, one source), only one will have correct mirrors.
• A note in static/skill.md explaining the asymmetry would help agents that hit a "the docs say X but the .md says Y" mismatch.

---

✅ What I liked

• Slug strategy: slug: /integrations/coding-agents/claude-code/local keeps URL hierarchy clean while letting the source files stay flat. My llms.txt section map keys off URL prefixes, so this works without changes.
• DocsMode value component: clean React shape (PublishedOnly / SourceOnly / DocsModeValue with published / source slots). Easy for authors to use.
• onBrokenAnchors: 'throw': good catch — pairs well with the existing onBrokenLinks: 'throw' and would have caught some cross-link drift early.
• Heading anchor UX: copy-link-on-click is a real improvement for humans; just needs the markdown-conversion concession above.
• Logo treatment: srcDark for logo-full-white.svg is the right Docusaurus pattern.
• OpenAPI integration page: the new openai-agents page is a meaningful addition.

---

Suggested order

1. Restore the six removed deps in package.json + package-lock.json (blocker 1).
2. Drop regen:api from prebuild/prestart; keep write:docs-mode (blocker 2).
3. Pick a heading-fix approach (blocker 3) — option 3 (CSS pseudo-element) is the lowest-coupling path.
4. Land PR #6 first (it's small and orthogonal), then rebase this PR on the result.
5. Re-run npx afdocs check https://docs.atomicmemory.ai --format scorecard against the deploy preview to confirm the score didn't regress.

Happy to send these as a follow-up commit on the branch if useful — let me know.