{
  "markdown": "# Superbee documentation\n\nThis repository contains Superbee's public, source-grounded documentation bundle and the minimal\ntooling that publishes it as a human site.\n\n```text\nverified product evidence\n  -> public .superbee bundle\n  -> one superbee/publication snapshot\n  -> codebase-documentation recipe + bundle-native publication model\n  -> one Recipe Studio-compiled @superbee/docs-projection projection\n  -> Portal site at docs.getsuperbee.com + conventional MkDocs reference output\n```\n\nThe repository is public by design. Private planning, credentials, security work, and unpublished\ncommunications belong elsewhere.\n\n## Documentation selection\n\nThe installed `codebase-documentation` recipe defines Documentation System, Documentation\nPublication, Documentation Section, and Documentation Trigger Kinds. Ordinary documents under\n`documentation-systems/`, `documentation-publications/`, and `documentation-sections/` own the\nrenderer-neutral product identity and selection. Sections name ordered primary pages; the\npublication names additional public pages that both outputs include outside navigation. Adapters\nmust not follow links to expand that explicit selection.\n\n`portal.config.json` now carries only the publication identity and target/build overlays such as\nbrand assets, agent guidance, diagrams, indexing, Views, routes, and deployment settings. Recipe\nStudio compiles the installed recipe and the linked bundle records into one projection. It rejects\nmissing pages, duplicate selection, navigation/support overlap, invalid operational exposure, or\nrecipe drift before either output is built.\n\nBoth outputs publish a bounded `llms.txt` over that exact selection. Documentation pages advertise\ntheir byte-exact Markdown source and the root discovery index; operational maintenance records stay\ninspectable in the complete public bundle without entering these curated agent surfaces.\n\nThe optional `documentation.guidance` binding carries the document id, heading, and label of one\nsection of one already-selected page that `llms.txt` quotes as its \"when to use\" guidance. Only the\npointer lives in configuration. The quoted bytes and every link inside them come from\nthat published document, so the entry point can never become a second content authority, and the\nbuild fails closed if the heading moves, is duplicated, gains a nested heading or code fence, or\nlinks to something outside the selection. It also refuses any link or markup shape the renderer\ncannot resolve into an absolute published URL -- a titled or angle-bracketed inline target, a\nreference-style link or its definition, an autolink, a raw HTML element or comment, or an indented\ncode block -- because a page-relative link copied into `llms.txt` resolves against `/llms.txt`\ninstead of the page it came from.\n\n## Agent-facing responses\n\nAn unknown documentation URL returns a real 404 carrying `404.html`, whose Markdown twin `404.md`\nholds the same recovery facts. Both link to the documentation index, `llms.txt`, and the sitemap\nwith absolute URLs, because a recovery response is served from whatever path the reader requested.\nCloudflare selects those bytes through the `not_found_handling: \"404-page\"` asset setting.\n\nThe Markdown access contract is explicit URLs, not `Accept:` content negotiation. The reviewed\nevidence in `research/agent-docs-discovery-surfaces` ruled negotiation a layer violation for this\nstack because it would make the edge a second renderer over digest-bound bytes, so the origin serves the\n`.md` sibling every page advertises and deliberately emits no `Vary: Accept`. Advertising a\nnegotiation the origin does not perform would fragment every shared cache in front of it while\nchanging nothing an agent receives. Portal's production verifier asserts that absence.\n\nDocumentation pages carry canonical, Open Graph, Twitter card, and product JSON-LD built only from\nthe projection's own product facts and this site's URL. No postal address, contact, social image, or\nlegal identity is emitted here; those facts belong to the public marketing site, which owns them.\n\n## Development\n\nNode.js 22.12 or newer is required.\n\n```bash\nnpm ci\nnpm run source:sync\nnpm run portal:build\nnpm run mkdocs:sync\nnpm run check\n```\n\n`npm ci` installs the exact Portal and Superbee packages recorded by the lockfile. The source sync\nkeeps an exact Superbee checkout only for source-grounded architecture checks. The Portal build\ncaptures one source snapshot and compiles the same explicit\n52-document selection (40 navigated and 12 supporting), brand asset, relationships, and eight\nadmitted diagrams into one projection consumed by both Portal and MkDocs. The\n`@superbee/docs-mkdocs` package\nowns the pinned uv command sequence: `mkdocs:sync` installs the exact locked Python environment\nonce, while `mkdocs:build` and repository checks are frozen and offline. Before changing the source\npin or package versions,\nconfirm that no `*.apply-intent.json` transaction journal is pending; finish or roll back that\noperation with the package version that created it first. Journals\ncontain local paths and exact recovery preimages and are intentionally ignored by Git.\n\nThe adoption is one atomic repository change. If the private compiler or bundle-native model must\nbe rolled back, revert the adoption commit and run `npm ci`; that restores the prior docs-site/v2\nconfiguration and local adapters together. Do not delete only the installed conventions or model\ndocuments while docs-site/v3 remains active, because compilation intentionally fails closed on a\nmissing or drifted recipe.\n\n## Release documentation\n\nNavigation and maintained pages use the stable `releases/current` and `sources/current-release`\nbundle identities. The reader-facing `releases/release-notes` page lists the current release and\nimmutable prior releases, while migration guidance stays beside it in navigation.\n\nThe daily release-freshness workflow compares the documented release with the public npm `latest`\npackage, GitHub release, and exact Git tag. Run the same deterministic probe locally at any time:\n\n```bash\nnpm run docs:release:status\n```\n\nWhen it reports `update_required`, the output carries the exact package, integrity, source commit,\npublication date, release URL, and generated GitHub notes. It also names the reader-facing fields\nthat still require agent judgment and the documentation-impact events to query. A verified release\nthen updates the stable identities, creates immutable versioned records, reconciles the release\narchive and selection, and updates the exact site version with one idempotent command:\n\n```bash\ncp examples/release-input.example.json /tmp/superbee-release.json\n# Fill the handoff with facts and verification from the completed release.\nnpm run docs:release -- --manifest /tmp/superbee-release.json\nnpm run docs:release:check\n```\n\nThe JSON file is ephemeral release-process input, not another persisted documentation authority.\nThe command writes release documents through Superbee, refuses to alter existing version history,\nand updates the bundle-native Documentation System and Publication records when needed. It\nconverges to a no-op when retried and never invents the summary, changes, user action,\ncompatibility, recovery, supported platforms, or verification performed. Review those fields\nagainst the release and query the returned impact events before opening the documentation pull\nrequest. The repository check rejects a package version pinned in ordinary pages; exact versions\nremain available in release, evidence, and migration records.\n\n## Deployment\n\nPortal builds the immutable public site artifact into `dist`. The public\n`@superbee/portal-cloudflare/static-assets` adapter then verifies that complete artifact and\natomically assembles `deploy`: every inventoried byte plus only the host configuration Cloudflare\nconsumes and does not serve. The two directories stay separate because `dist` is inventory-exact.\nPortal must be able to reject any extra or changed byte in it.\n\nThe package derives `_headers` from the artifact's declared response policy and exact media types.\nIt also derives every canonical 307 HTML alias from the artifact's hosting requirements. This\nrepository contributes only two site-specific rules: `/docs` and `/docs/` return 301 redirects to\nthe canonical root. Each names one exact path, so every other missing route still reaches the\npublished recovery body as a real 404. `scripts/deployment-assets.mjs` is the small consumer binding\nfor that policy. It does not duplicate Cloudflare limits, MIME tables, integrity checks, or\nfilesystem replacement logic.\n\n`scripts/cloudflare-worker.mjs` is similarly small. It exports the package's verified public Portal\nhandler under a stable Wrangler entry path. Portal owns byte validation, route admission, recovery,\nopaque downloads, View isolation and bridge behavior, and the live deployment-effect identity.\nWrangler keeps presentation routes asset-first so generated headers and canonical redirects apply,\nthen sends `/data/*`, `/bundle/*`, and the View bridge to the Worker for verified dynamic policy.\n\nThe MkDocs adapter independently materializes a conventional reference site under ignored\n`.tmp/mkdocs/site` from the same owned projection; it is validated but not deployed by this\nrepository. Validate the exact artifact, Cloudflare assembly, and staged runtime locally:\n\n```bash\nnpm run portal:build\nnpm run cloudflare:check\nnpm run cloudflare:reconciliation:check\n```\n\nAfter a deployment, compare the live origin against the exact artifact this repository built:\n\n```bash\nnpm run verify:production -- --base https://docs.getsuperbee.com --dist dist\n```\n\nThe command is a thin consumer of Portal's host-neutral verifier. Portal checks exact status, bytes,\nmedia types, response headers, audience policy, fallback behavior, content negotiation, canonical\nHTML routes, and their exact 307 aliases from the artifact's hosting requirements. This repository\nadds only its page metadata, advertised Markdown-alternate, and two guessed `/docs` entry-route\nassertions to the same receipt. No static-byte or canonical-redirect capability is waived.\n\nProduction activation belongs to `.github/workflows/verify-production.yml`, not to Cloudflare Git\nbuilds or a bare Wrangler command. Its uncredentialed build job checks out the exact `main` commit,\nexpands repository history, runs the deterministic build and staging checks, and uploads only the\ncompleted `dist` artifact. The reconciliation job downloads those exact bytes, assembles the\npackage-owned Cloudflare layer without rebuilding the site, and re-resolves `origin/main`\nimmediately before activation. A changed desired commit fails closed.\n\nOnly the reconciliation step receives `CLOUDFLARE_API_TOKEN`. It calls the package's public\nreconciler through `scripts/reconcile-cloudflare.mjs` with an immutable source, site, and toolchain\nprovenance tuple. The reconciler inspects provider generation, stages and digests the complete\nactivation unit, activates with strict generation protection, then externally verifies the live\neffect. If a new activation fails verification and the prior generation was verified, the package\nrolls back and verifies recovery. The workflow concurrency group never cancels an in-flight run, so\none production target has one serialized activation stream.\n\nThe workflow then runs the Docs-specific verifier over every expected status, byte digest, media\ntype, response header, redirect, fallback, and admitted View. An `if: always()` step uploads both\nthe reconciliation receipt and the Docs verification receipt for 30 days, including bounded\npreflight failures and verified rollback outcomes. Its daily scheduled run uses probe mode and does\nnot mutate production, so deployment drift is detected against the current exact artifact.\n\nCloudflare's repository integration must remain disabled while this workflow is the production\nwriter. Enabling both would create two independent activation authorities. The\n`npm run cloudflare:check` command remains a credential-free dry run, not deployment agreement, and\nthis repository intentionally exposes no `cloudflare:deploy` or `cloudflare:preview` script. `main`\nis the production branch.\n\n## Diagrams\n\nMermaid does not execute inside Superbee Markdown. Diagram source is compiled into a source-bound,\nadmitted static SVG whose exact committed bytes both documentation outputs consume:\n\n```bash\nnpm run diagram:build   # apply source -> public bundle static SVG + v3 receipt\nnpm run diagram:check   # prove checked-in source/SVG/receipt agreement\nnpm run portal:preview  # inspect the exact Portal artifact locally\n```\n\nThe exact `@superbee/docs-tooling` package owns both reusable compilation and the explicit,\nnamespace-bounded `superbee-docs diagram apply` publication conductor; this repository owns its\nsource, manifest, configuration, and receipt. Diagram source uses directive-free flowchart syntax\nwithout font overrides and printable ASCII in v1. Browser layout geometry may\ndiffer slightly across operating systems, so\nchecks re-render for safety and accessibility while source-bound projection metadata detects drift;\nboth output adapters separately pin the exact committed static SVG bytes. The old View HTML and\nregistrations remain byte-for-byte predecessor evidence; they are not maintained publication output.\n\nIf `diagram:build` reports an interrupted apply, run `npm run diagram:rollback` before retrying.\nThat repository command supplies the required root and config arguments. Apply never removes stale\npublications merely because the local receipt no longer lists them; pruning is a separate,\nexplicitly authorized lifecycle operation.\n",
  "bytes": 13686,
  "sha": "e6473f971f4f264f084ec9921aa3d95df3d12707357c2f89e4f659967ba2378e",
  "repo_slug": "holaxis-ai/superbee-docs",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_holaxis_ai_superbee_docs_superbee_index__eb702aa1/readme"
}