Skip to content

Documentation Governance Standard

Standard ID: STD-DOC-001 Purpose: Establish the immutable rules for documentation location, naming, lifecycle, and change impact across the Bluefly platform.

Scope: §1–§7 govern the blucity-docs repository. §8 governs the estate — the boundary between this repository, a project's docs/, a project's .agents/, and a project's GitLab wiki, and the publication path from Git to ContextControl and Gemini Notebook. Naming and front-matter detail for documents inside Engineering-Standard/ is delegated to naming-convention-and-taxonomy.md (STD-034); repository layout outside this one is delegated to repository-structure-standard.md (STD-REPO-001). Those standards are referenced, not restated.

1. Documentation Location Standard

Documentation is code. Its canonical location is the blueflyio/blu/blucity-docs GitLab repository, on release/v0.1.x merging to main — not any workstation or NAS mount. Paths below are repository-relative; do not hardcode a local mount (/Volumes/...) or workstation (~) path as canonical anywhere in this repository's own documentation.

Reference resolution (binding): cite documentation by repository-relative path (Engineering-Standard/..., products/..., Playbooks/...), optionally with an explicit Git ref or commit SHA when the exact version matters. A host-absolute path is never a documentation-authority reference — absolute paths may still be valid when they intentionally describe an implementation worktree, runtime location, mount, or execution path. When auditing a stale reference, classify it before editing: (1) documentation-authority claim — correct it to the repository-relative canonical path; (2) implementation or runtime path — preserve it unless the runtime topology itself is stale, and route that correction to the owning architecture/runtime document; (3) historical record under _ARCHIVE/ — do not rewrite history merely to match current topology.

Top-level directories, OBSERVED 2026-09-20 against release/v0.1.x after trunk reconciliation. This list is the permitted set: a directory not named here does not exist in this repository, and one that exists but is not named here is a defect in one of the two.

  • Engineering-Standard/ (CANONICAL_ALLOWED): cross-platform authoritative engineering guidance (constitutions, architecture boundaries, standards, catalogs, authority sources). Its internal layout is governed by ES-STRUCTURE-001 and routed by §7.3 below.
  • Playbooks/ (CANONICAL_ALLOWED): executable operational procedures (recovery, deployment, incident response). Capitalised. The lowercase Playbooks/ spelling used elsewhere in older text is the same directory on a case-insensitive filesystem and the wrong spelling in Git; cite it as Playbooks/.
  • ledger/ (CANONICAL_ALLOWED): the evidence home — audit receipts, command output, verification records, dated operator directives, handoffs. Evidence does not become architecture. Append-only: a ledger entry records what was observed at a point in time and is superseded by a later entry, never edited to agree with the present.
  • products/ (CANONICAL_ALLOWED): product descriptions, architecture, offerings — documentation about products, never their implementation source (see governance/documentation-implementation-boundary-contract.md).
  • strategy/ (CANONICAL_ALLOWED): durable cross-product strategy and go-to-market position. Not a plan tracker — active work is Beads.
  • projections/ (CANONICAL_ALLOWED): derived read-models (currently Dolt SQL exports). Read-only; MUST declare SOURCE_AUTHORITY=, GENERATED_AT=, DERIVED_FROM=. Never hand-edited.
  • scripts/ (CANONICAL_ALLOWED): validation and generation tooling for this repository's own CI. Not a general script dump; anything an operator runs by hand belongs in Playbooks/ or a CLI.
  • docs-upstreams/ (CANONICAL_ALLOWED): Git submodules of upstream documentation (e.g. Gas City). Read-only mirrors — never edited here; corrections go upstream.
  • .agents/ (CANONICAL_ALLOWED): this repository's own agent contract and skills. Governed by STD-REPO-001 §2, not by this section.
  • Repository-Local (other repositories): owns ONLY repository purpose, dev setup, build instructions, tests, and API usage. Repository docs MUST reference central standards rather than duplicate them. See §8.

Retired names. Evidence/, Research/, reference/, assets/ and _ARCHIVE/ were named as top-level homes by earlier revisions of this standard and do not exist in this repository. ledger/ is the evidence home; static reference material lives in Engineering-Standard/reference/; superseded material is marked status: superseded in place rather than moved to an archive directory. Do not recreate the retired names, and treat any link pointing into them as a broken link to be retargeted (§4).

No other top-level directory is permitted without updating this list first.

2. Documentation Naming Standard

  • Use stable, descriptive, lowercase kebab-case filenames (e.g., documentation-governance-standard.md).
  • Allowed conventional names: README.md, AGENTS.md, llms.txt, OWNERSHIP.md, CLAUDE.md, GEMINI.md, CHANGELOG.md, CONTRIBUTING.md, SECURITY.md, LICENSE. Published-site AI companions (ai.txt, developer-ai.txt, faq-ai.txt) are allowed only as LLM-facing indexes (see Drupal profile below), never as a second constitution.
  • Prohibited terms: final, latest, new, newer, updated, fixed, real, copy, v2, v3, draft-final, old, temp, misc.
  • Do not rename files only to satisfy style if it breaks established tooling.
  • Exceptions to kebab-case — allowed only when justified by one of:
  • a formal identifier scheme with its own numbering convention (e.g. ADR-0008-*.md, APPLE-001-*.md)
  • an externally-defined protocol/spec name that must match upstream exactly
  • a generated filename whose casing is produced by the generator, not hand-chosen Do not extend this list to justify an otherwise-ordinary document keeping PascalCase or SCREAMING-CASE out of habit.

3. Documentation Lifecycle

Every discovered document must possess ONE state:

  1. CANONICAL
  2. REFERENCE
  3. REPOSITORY-LOCAL
  4. PLAYBOOK
  5. EVIDENCE
  6. RESEARCH
  7. GENERATED
  8. HISTORICAL
  9. ARCHIVED
  10. SUPERSEDED
  11. CANDIDATE-DELETE

Canonical status requires: correct owner, correct location, current content, active references, and no stronger competing document.

3.1 Knowledge Promotion Tiers

Knowledge is not born canonical. Every written finding moves upward through three tiers, in one direction, and each transition is gated (§3.2). The tiers map onto the top-level directories in §1 and onto the Drupal-specific promotion classes in the Bluefly.io content-architecture specification §28 (products/Bluefly.io/bluefly-io-content-architecture-and-central-drupal-knowledge.md), which is the worked example of this section for Drupal findings.

Tier Home Authority What belongs here
1 — Working knowledge ("work it out") the owning project repository or its Bead; Research/ when it must live in this repository (exit condition required, §1) none — never cited as policy hypotheses, proposals, investigations, exact entity IDs, temporary scripts, one-off migration exceptions, current branch/MR state, local bug reproduction, site-specific copy
2 — Verified evidence ("prove it") ledger/ evidentiary — records what was observed, measured, or executed, by whom, when dated audits, measurements, implementation receipts, migration results, failures and corrections, proof that supports a later standard
3 — Canonical knowledge ("govern by it") Engineering-Standard/reference/ (reference knowledge), Engineering-Standard/standards/ and rules/ (normative), Playbooks/ (repeatable execution method) canonical — binding on agents, CI, and contributors current ecosystem maps and ownership matrices (reference); rules Bluefly has accepted as how work is performed (standard); lessons that have become a repeatable procedure (playbook)

Ledger entries are append-only: a correction is a new sibling entry, never a rewrite. Evidence supports a standard; it never becomes one without passing Gate 2.

3.2 Promotion Gates

Gate 1 — working knowledge → ledger/. Every condition must be YES:

Condition Meaning
EVIDENCE_EXISTS Primary artifacts exist: tool output, runtime logs, receipts, measurements.
CLAIMS_VERIFIED Every mechanism or capability claim was tested against real runtime or source code.
CONTRADICTIONS_RESOLVED No unresolved conflicting claim remains in the artifact.
SOURCE_PROVENANCE_RECORDED Sources, upstream commit SHAs, pipeline IDs, and tools are cited.
STATUS_CONFIRMED The observed state is certified by the executing agent or a witness.

Any NO → the material stays in Tier 1.

Gate 2 — ledger/ → Engineering-Standard/ or Playbooks/. Every condition must be YES:

Condition Meaning
VERIFIED Backed by durable ledger receipts or verified upstream documentation.
DURABLE Describes permanent architecture or accepted practice, not transient runtime state.
ADOPTED Bluefly has accepted it as policy, architecture, or repeatable method (BLU or operator approval).
EXISTING_OWNER_CHECKED qmd query or grep located the existing canonical owner (§7.6) and the change extends it in place.
NO_DUPLICATE_CREATED No parallel, -v2, or second-authority file was created.

Any NO → the material stays in ledger/ as reference proof.

3.3 Index and Naming Consequences

  • Engineering-Standard/indexes/BLU-BIBLE.md indexes Tier 3 documents only. Tier 1 material and individual ledger entries are never listed alongside canonical documents as equal authority; BLU-BIBLE may link to a ledger index, not to receipts. A Tier 1 or Tier 2 document found in BLU-BIBLE is removed from the index; if it also sits under Engineering-Standard/, it is demoted — moved to its tier, links purged, and a receipt filed in ledger/.
  • Tier markers (provisional, draft, wip, temp, v2, new, fixed) are prohibited in Engineering-Standard/ filenames and titles. Status is carried by the lifecycle state above and by front matter, not by the filename (§2).

4. Change-Impact Alignment Workflow

Platform changes often invalidate multiple documents. Any agent making a platform-affecting change MUST execute the following documentation-impact workflow:

  1. Identify: Identify the exact capability changed.
  2. Search QMD: Search QMD for all documents mentioning the capability.
  3. Identify Canonical: Identify the canonical standard affected.
  4. Update Local: Update repository-local docs.
  5. Update Playbooks: Update affected playbooks.
  6. Update Visuals: Update diagrams and examples.
  7. Mark Superseded: Mark old or competing documents as SUPERSEDED and archive them.
  8. Verify Links: Verify all cross-references and links.
  9. Reindex: Reindex the search system (qmd).
  10. Receipt: Include the documentation impact in the MR (Merge Request) receipt.

This sequence is part of the core engineering workflow. Work is not complete until documentation is aligned.

5. Repository Documentation Ownership

  • Drupal CMS Projects: Any repository containing an underscore _ (e.g., agent_api, ai_agents_claude) is a Drupal CMS project. Its canonical documentation is owned by the Product (Drupal).
  • Platform/Infrastructure: Any repository using hyphens (e.g., blu-cli, agent-docker) is owned by the Engineering Standard, unless repository evidence proves otherwise.

For a full index of Canonical Documents and Archives, consult: * Engineering-Standard/governance/canonical-index.md * Engineering-Standard/governance/repository-classification.md

6. Project Root Interface Contract

Repository root is an interface, not a dumping ground. Applies to active Bluefly-owned software projects — not upstream mirrors, vendored source, archived repos, generated-only artifacts, or repos whose ecosystem requires a different top-level contract.

See also: repository-structure-standard.md owns everything below the root-file layer — the .agents/ internal taxonomy (skills/, context/, roles/), tool-state directory boundaries (.beads/, .qmd/, .codegraph/, .claude/), .well-known/, .gitlab/duo/, openapi/, packages/, scripts/, src/, container placement, and tests conventions. This section owns only the root-file contract below; do not duplicate the above there.

Mandatory Root Files

File Contract
README.md What the project is, does, how to use it; dev setup, build, test
AGENTS.md Scoped operational instructions (always-on; keep small)
llms.txt Retrieval/discovery index (llmstxt.org v2)
OWNERSHIP.md What this project owns, what it doesn't, upstream/downstream, authority
.agents/ Agent capabilities, skills, and scoped context — preserve; never delete, flatten, replace, or bypass

Short starting templates for all four, plus the conditional ARCHITECTURE.md and the thin CLAUDE.md adapter, live at Engineering-Standard/templates/repository-root/. Instantiate one, delete sections that don't apply. Do not leave placeholder sections in production repositories.

These root surfaces have distinct purposes — do not collapse them into one document. They implement three external contracts:

File Audience External contract Size rule
README.md Humans agents.md — keep READMEs for humans Short; no agent operating law
AGENTS.md Coding agents agents.md — how to work in this repo Operational only. Nested files: closest AGENTS.md to the edited file wins; an explicit user prompt overrides both. Do not paste catalogs, ADRs, or Engineering-Standard prose.
llms.txt Any LLM fetching this path llmstxt.org v2 Tiny index. Detail lives behind links.
CLAUDE.md / GEMINI.md One vendor Tool requires that filename Thin pointer to AGENTS.md (< 10 lines). Claude Code auto-loads CLAUDE.md every session (context window); keep it under 200 lines, prefer the pointer.

llms.txt v2 format

One llms.txt per path it covers. Agents use the most specific file when more than one applies. The file must follow llmstxt.org v2, in this order:

  1. Optional BOM
  2. An H1 with the project or site name (required; the only required section)
  3. A blockquote with a short summary
  4. Zero or more markdown blocks without headings — interpretation notes
  5. Zero or more H2 sections whose bodies are file lists: - [name](url): optional notes
  6. By convention, an H2 named Optional for links an agent may skip when context is tight

Links must point at LLM-friendly markdown (repo files, or HTML pages that also publish .md / rel="alternate" type="text/markdown"). Do not paste the linked content into llms.txt. The index must stay small enough to load in one context window; the encyclopedia belongs behind the links.

Where a site is published, also expose rel="describedby" to that path's llms.txt. Path-local files (/docs/llms.txt) cover that path, not the whole origin. Do not put llms.txt only in /.well-known/ — authors who control a subpath cannot publish there.

Agent context budget

Auto-loaded instruction files compete with real work for the same window.

  • Put always-on operating law in root AGENTS.md.
  • Put directory-specific conventions in nested AGENTS.md or path-scoped rules (.claude/rules/ with paths:), not in the root file.
  • Put catalogs, org lists, and "further reading" in llms.txt Optional, not in AGENTS.md or CLAUDE.md.
  • Do not auto-load encyclopedias. File reads dominate context; be path-specific. Use a subagent for research-heavy reads so those tokens stay out of the parent window.
  • Claude Code: /compact before a long new task. Do not use a reasoning session as a timer, poller, or message bus. Auto memory is the first 200 lines or 25KB of MEMORY.md — keep it small. After compaction, skill descriptions do not reload; keep important skill instructions at the top of SKILL.md.
  • Nested llms.txt only at path boundaries that need a different index (a published subpath, a monorepo component root). Identical copies in src/, tests/, ci/, web/modules/**, or every subdirectory are CONTEXT_POISONING: most-specific path wins, so a cloned dump replaces the curated root index and burns context. Delete those clones; do not "sync" them.

Conditional Root Files

Include only if applicable:

File When
ARCHITECTURE.md System design is non-obvious; durable structure only
DEPLOY.md Application/service deploys independently (see repository-structure-standard.md §11); never for libraries that don't deploy on their own
CONTRIBUTING.md External contributions accepted or complex contributor workflow
SECURITY.md Security contact, vulnerability reporting policy (prefer a pointer to org-wide policy)
CHANGELOG.md Releases/packages published; user-facing changes only, not a work journal
LICENSE Legal requirement matching package.json/composer.json license
CODEOWNERS Actual human/team ownership is known; don't invent owners to populate it

llms.txt Variants Rule

Do not create llms-full.txt, llms-detailed.txt, or other parallel indexes. v2 already has an Optional section for skippable links. Extra files are a context-window defect unless an engineering requirement is documented in AGENTS.md.

If a single llms.txt is insufficient:

  1. Verify: Confirm that standard llms.txt genuinely cannot express the routing. (Usually it can.)
  2. Document in AGENTS.md: Explain why multiple index files exist and how agents should choose between them.
  3. Name clearly: Use explicit, stable names; never use suffixes like -new, -old, -v2, -temp.
  4. Deprecate unused variants: Mark stale llms.txt files for deletion or archive them.

Default: One llms.txt per repository. That is sufficient.

Prohibited Root Files

DO NOT create these to track live engineering state — a project may use one only when a proven product or ecosystem contract owns it:

  • TODO.md, STATUS.md, PLAN.md, NOTES.md, ROADMAP.md — work lives in Beads (bd)
  • ISSUES.md — issues live in GitLab, not repository markdown
  • CONTEXT.md, MEMORY.md, PROMPT.md — use llms.txt, not competing files
  • SOUL.md, MISSION.md, VISION.md, AUTHORITY.md — mission belongs in README/OWNERSHIP, authority belongs in OWNERSHIP
  • VISION.md, QUICKSTART.md, INSTALL.md, INTEGRATION_GUIDE.md, PROJECT_SUMMARY.md — fold into README.md and AGENTS.md; do not sprawl root

Why: Beads own durable work state. GitLab MRs own source delivery. CI/runtime own verification. Repository markdown cannot be authoritative for live state. Root file sprawl obscures the canonical interface.

Vendor-Specific Agent Files

AGENTS.md is the canonical repository agent instruction surface. Do not maintain divergent full copies (CLAUDE.md, GEMINI.md, other tool-specific files) that merely repeat it.

If a tool genuinely requires another filename (verified by actual tool documentation, not assumption):

  • Use only a thin pointer file (target < 10 lines, hard cap 200) that references AGENTS.md. Claude Code auto-loads CLAUDE.md every session; a second copy of the contract wastes the context window. 
    # <Tool Name> Instructions

See [AGENTS.md](AGENTS.md) for the authoritative repository operating contract.
See [llms.txt](llms.txt) for the on-demand index.

  • Claude Code auto-loads project CLAUDE.md and ~/.claude/CLAUDE.md before the first prompt. A resource dump in either file is paid on every session. Keep Claude-only setup here; keep operating law in AGENTS.md.

  • Do not maintain multiple independently edited agent constitutions.

  • Do not create per-developer variants (e.g., CLAUDE.local.md, GEMINI.local.md).
  • Verify tool requirement before creating the file.
  • Delete outdated vendor files when a tool ceases to be active.

Keep AGENTS.md authoritative — it is the single operating contract.

Root Hygiene

Every root item must be justified as one of:

  • STANDARD_PROJECT_INTERFACE
  • ECOSYSTEM_REQUIRED (upstream mandate)
  • BUILD_REQUIRED (CI files, build scripts)
  • GOVERNANCE_REQUIRED (license, CODEOWNERS)
  • SOURCE_ENTRYPOINT (main entry file)

Generic Bluefly-owned directories (scripts/, stuff/, misc/, helpers/, utils/, temp/, old/, backup/, scratch/) are suspect until justified — they are not automatically illegal, and upstream/ecosystem convention always wins. Do not rename a framework-required or ecosystem-standard directory merely because its name appears above.

Ecosystem-Native Profiles

Preserve framework conventions; do not force uniform internal structure across project types.

npm/TypeScript: src/, tests/, package.json, one lockfile (matching the selected package manager: package-lock.json for npm, pnpm-lock.yaml for pnpm, yarn.lock for Yarn), bin/ for actual CLI entrypoints only. Published packages must not depend on workstation-relative authority (no hidden local path dependency, no ../../SomeRepo production authority, no symlink-based package authority).

Drupal module: <machine>.info.yml, composer.json, src/, tests/src/, config/install/, config/schema/, templates/, Drupal-native *.routing.yml/*.services.yml/*.permissions.yml/ *.libraries.yml at extension root where Drupal requires it.

Drupal theme: <machine>.info.yml, <machine>.libraries.yml, templates/, css/, js/, components/ only when the theme's component model requires it.

Drupal recipe: recipe.yml as canonical entrypoint, config/, README.md. No custom PHP; do not turn a recipe into a module to satisfy a generic source layout.

Published Drupal site: drupal/llms_txt owns the live /llms.txt endpoint. Prefer contrib drupal/llm_support (llms.txt + Markdownify + Token Filter) for markdown page variants rather than custom PHP. Repo-root llms.txt is the coding-agent index. Optional public companions ai.txt, developer-ai.txt, and faq-ai.txt are LLM-facing indexes that link out; they must follow llmstxt.org v2 list form and must not restate AGENTS.md. Serve them via the module/recipe, not a hand-rolled controller. HTML pages agents need should expose rel="alternate" type="text/markdown" and rel="describedby" to the covering llms.txt.

IaC/Terraform: main.tf, variables.tf, outputs.tf, modules/, environments/, .tfvars.example (no secrets).

Monorepo (meta-repository containing multiple sub-projects): Root README.md describes the monorepo purpose and component map. Root AGENTS.md defines cross-component rules. Root llms.txt indexes component locations. Each sub-project has its own local interface contract (README, AGENTS, llms.txt scoped to that component). Do not force a single README/AGENTS/llms across all components; reference the component-local docs from the root index.

Do not create a project profile until a real project type requires one.

Artifact Staleness and Cleanup

Agent, version, and configuration artifacts in the repository root can drift out of sync with current working versions:

  • Stale agent files (e.g., agent-v0.1.0.yml, agent.old.yml) — Do not leave versioned agent artifacts at the root. Use agents/ directory or .agents/ contract directory. Delete or move superseded versions.
  • Outdated configuration (e.g., .env.example, old docker-compose.yml) — Update to match current reality or delete. Do not commit as historical record.
  • Temporary build artifacts (e.g., build.log, .tmp/, __pycache__) — .gitignore strictly. Never commit.

When an agent artifact is superseded: create a cleanup commit that removes the stale version and updates AGENTS.md to reflect current location. Do not leave versioned artifacts as historical record.

Context-Poisoning Classification

Class Action
CANONICAL Keep; version-control
DURABLE Keep; track lifecycle
GENERATED .gitignore if build output; never commit
DUPLICATE Delete or archive
STALE Supersede and archive
CONTEXT_POISONING Delete (copied prompts, AI-generated plans, session notes)
UNKNOWN_OWNER Preserve; investigate separately; never destroy

Do not modify immutable historical evidence merely to make current naming look clean. Annotate legacy literals instead: LEGACY_NAME=<literal>, CANONICAL_OWNER=<current-name>.

Beads Rule (Hard Requirement)

Beads (bd) own durable work state. GitLab Issues are NOT the Bluefly work ledger. Canonical flow: BEAD → branch → commit → MR → CI → merge → receipt → BEAD CLOSED. Do not maintain issue lists, sprint metrics, or live task tracking outside Beads in repository files.

7. System Directive — Agent Knowledge & Documentation Routing Contract

System Directive — BluCity-Docs is the Knowledge Authority

The canonical documentation repository is: 

blueflyio/blu/blucity-docs (BluCity-Docs)

The workstation is ephemeral. Do not create random Markdown files at the repository root, do not create new top-level directories because a document does not immediately fit, do not dump reports into Engineering-Standard, and do not store meaningful project documentation in ~/.cursor, ~/.claude, ~/.gemini, agent private memory, chat threads, /tmp, or random repository roots. If deleting this workstation loses knowledge required to understand or continue Bluefly work, the session exit contract has failed.

7.1 Authority Model

Surface Canonical Role
GitLab Source code & release authority
Beads / Dolt Work, execution state, blockers, dependencies, task evidence
BluCity-Docs Curated durable knowledge authority
Implementation repo /docs Implementation-specific documentation
Oracle Live runtime operational truth
ledger/ Immutable verification artifacts, receipts, audits, and captured directives
projections/ Derived views of authoritative state (never mutated directly)
ContextControl Governed delivery of the above to agents — selection and scope, never authorship (§8.4)
Scratch Temporary analysis only, and outside this repository — there is no Scratch/ directory here

Do not turn documentation into a duplicate work ledger. Do not turn Beads into architecture documentation. Do not turn projections into authority.

7.2 Classify Before Writing

Before creating, editing, moving, or deleting any document, classify the information into one of: POLICY | ARCHITECTURE | AUTHORITY | STANDARD | RULE | DECISION | OPERATING_MODEL | INFRASTRUCTURE | INTEGRATION | PLATFORM | RUNTIME_REFERENCE | CAPABILITY_CATALOG | TOOL_REFERENCE | PRODUCT | PLAYBOOK | EVIDENCE | FACT | PROJECTION | IMPLEMENTATION_DOC | TEMPORARY | WORK

Then route it to its existing owner. Do not create a new home until you have proven no appropriate home exists.

7.3 Engineering-Standard Directory Routing Contract

Use Engineering-Standard/ subdirectories deliberately: - architecture/: System boundaries, control plane, data plane, digital factory, Drupal ↔ Gas City architecture. Explains what the system is, its major parts, and how they relate. (No point-in-time state). - authority/: Source-of-truth and ownership boundaries (e.g., GitLab owns source, Oracle owns runtime, Beads owns work, 1Password owns secrets). Answers: Who has authority over this concern? - catalog/: Inventories of canonical reusable capabilities (formulas, components, agents, skills, providers, packages). Answers: What capabilities exist, where is the owner, how to consume? (No implementation task tracking). - context-plane/: Durable rules & architecture for AI context, context injection, agent context, memory boundaries, and promoted knowledge. - decision-records/: Durable Architecture Decision Records (ADRs). Requires Context, Decision, Alternatives, Consequences, Status, Date, Owner. - glossary/: Canonical definitions of Bluefly terms (Bead, Polecat, Rig, City, Town, Order, Formula, Convoy, Proof, Capability Owner). One term, one canonical definition. - governance/: Governance models, approval authority, policy enforcement, compliance, review requirements, human vs machine authority. - indexes/: Generated or curated navigation into the knowledge base (agent-team.md, llms.txt, index maps). Points to authoritative docs; does not restate them. - infrastructure/: Durable infrastructure architecture & standards (Oracle estate, NAS role, Tailscale, networking, deployment architecture, IaC). - integration/: Durable contracts between systems (Drupal ↔ Gas City, GitLab ↔ Gas City, 1Password ↔ runtime). Explains boundary contracts, not temporary troubleshooting. - operating-model/: How Bluefly operates (continuous dispatch, autonomous factory, Mayor behavior, Witness model, worktree lifecycle, repository completion contract). - platform/: Durable platform-level design (agent platform, CMS platform, Digital Factory, Cloud platform). Sits above individual project repos. - reference/: Stable operational & reference data (known ports, command references, supported endpoints). Maintain and keep current; no raw audit dumps. - rules/: Hard prohibitions and invariants (e.g., no plaintext secrets, no feature → main, no local Beads, workstation owns nothing). Short and enforceable. - runtime/: Durable model of runtime behavior. (Live runtime truth comes from Oracle; docs describe the model). - standards/: Normative technical standards containing MUST, SHOULD, MAY, MUST NOT requirements. - templates/: Reusable document or execution templates only (ADR template, audit template). No completed instances. - tools/: Durable documentation about canonical Bluefly tools (blu, gc CLI, operator tooling).

7.4 Other BluCity-Docs Homes

  • ledger/: Immutable or point-in-time proof worth retaining. Answers: What did we observe, when, where, using what method, with what result? (If evidence creates work → create a Bead.) Use the sub-home that matches the artifact:
  • ledger/audits/ — a completed audit with a method and a result
  • ledger/evidence/ — raw observation captured during a session
  • ledger/receipts/ — proof that a named execution happened
  • ledger/directives/ — a dated operator directive, captured verbatim as input. A directive is evidence, not a standard. The curated standard that implements it lives under Engineering-Standard/standards/; the directive is never itself the normative text. Committing directive prose into standards/ creates a second authority competing with the standard written to satisfy it.
  • ledger/decision-records/ — not a home. ADRs live only in Engineering-Standard/decision-records/.
  • Playbooks/: Reusable operational procedures (How do I safely perform this recurring operation?). Only promote mature, stable procedures.
  • products/: Durable product-specific knowledge (products/Bluefly.io/, products/ContextControl/, products/AMCS/). Documentation about products only — application source belongs in the product's own repository.
  • projections/: Derived/read-model views (Mayor fact board, computed estate status). Projections are read-only and MUST declare SOURCE_AUTHORITY=, GENERATED_AT=, DERIVED_FROM=.

7.5 Facts & Audits Lifecycle

  • Live Operational Fact: Runtime authority (Oracle/Gas City). If historically relevant → Evidence/.
  • Durable Architectural Fact: Engineering-Standard/architecture/ or authority/.
  • Audits Lifecycle: Audits start in Scratch/ or generated evidence. At completion:
  • Durable architectural conclusion → merge into canonical Engineering-Standard/ owner.
  • Point-in-time evidence → save under Evidence/.
  • Discovered work → create Beads.
  • No remaining value → delete draft.

7.6 Knowledge Promotion & No-Duplication Rule

  • Promotion Flow: Scratch / Live Investigation → Classify → Canonical Owner → Delete temporary draft. The tiers each step moves between, and the gate each step must pass, are defined in §3.1–§3.2.
  • No Duplication: Always qmd query or grep BluCity-Docs before writing. Extend existing canonical files in place. Never create foo-v2.md, foo-fixed.md, foo-new.md.
  • README Files are Maps: Directory README.md files explain directory purpose and point to canonical docs; do not stuff full standards inside READMEs.
  • Tool Directories (.agents/, .claude/, .cursor/): Integration surfaces only, not documentation authorities. Extract substantive knowledge into BluCity-Docs.
  • Beads vs Documentation Test:
  • Describes work to happen? → Beads
  • Describes why system is designed this way? → Durable Docs (Engineering-Standard)
  • Proves what happened? → Evidence
  • Describes current derived state? → Projections
  • Explains repeatable procedure? → Playbooks
  • Explains one project repo? → Owning repo /docs

7.7 Documentation Exit Gate

Before completing any session, verify: 

[ ] No meaningful project docs left in ~/.cursor, ~/.claude, or ~/.gemini
[ ] No orphan markdown files in repository root
[ ] No duplicate canonical docs created
[ ] Every new durable fact has a canonical owner in BluCity-Docs
[ ] Every audit and verification artifact is dispositioned to Evidence/ or deleted
[ ] Every discovered execution task is recorded in Beads
[ ] BluCity-Docs working tree is committed & clean

8. Surface Boundaries — Central, Project, Agent Context, Wiki

§1–§7 govern this repository. §8 governs the boundary between this repository and the other surfaces a fact can land on, so that every file in the estate has one home and every agent knows which surface owns which claim.

The two layers, stated once:

The project repository answers "what is true about this project?" BluCity-Docs answers "what is true across Bluefly?" Do not mix them.

8.1 The four surfaces

Surface Owns Never
BluCity-Docs Cross-project doctrine: standards, rules, architecture, authority model, decision records, catalogs, playbooks, glossary. If a statement applies to many projects, this is the owner. Execution code; workspace-local state; runtime configuration a running system reads; a second copy of a project's own build instructions.
Project repo docs/ What is unique to that project: purpose, scope, current architecture, API reference, developer setup, build/test commands, dependencies, integration notes, deployment behaviour, project-only ADRs. authority: canonical. A copy of any Bluefly standard.
Project repo .agents/ Concise machine-operational context an agent needs to act correctly in that repository. Layout, including context/, skills/ and roles/, is governed by STD-REPO-001 §2 — not restated here. Doctrine copied from BluCity-Docs. Agent transcripts. Scratch notes. Duplicate spellings (.agent/, ai-context/, .claude/context/).
Project GitLab wiki Volatile operational notes with no review cycle: meeting notes, onboarding scratch, runbook drafts, "how to run this today". Being cited as authority by any standard, rule, ADR or playbook.

Estate-root exception. [ESTATE-ROOT]/.agents/ is not a project agent-context directory — it holds independent governed GitLab repositories (the Agent Capability Estate) and is treated as source, not context. The rules above apply to .agents/ inside a project repository.

8.2 The routing test

Ask, in order, and stop at the first yes:

  1. Does this statement apply to more than one project? → BluCity-Docs
  2. Does it describe work to be done? → Beads, not documentation
  3. Does it prove what happened at a point in time? → ledger/
  4. Is it a repeatable operator procedure? → Playbooks/
  5. Does it explain one repository to a human? → that repo's docs/
  6. Does an agent need it to act correctly in one repository? → that repo's .agents/context/
  7. Is it volatile, unreviewed, and true only today? → the project wiki

If none apply, the content has no home — which means it should not be written.

8.3 Reference doctrine, never copy it

Do not copy sections of BluCity-Docs into a project's README.md, AGENTS.md, CLAUDE.md, .agents/context/* or docs/. A project's AGENTS.md names the standards it follows and then states only that project's exceptions.

A copied rule is a second authority. When the original changes, the copy becomes a contradiction that no one is reviewing — and copied doctrine routinely drags workstation- absolute paths into repositories that then fail their own CI path checks.

Every .agents/context/ file must answer four questions in its own header: what is this context, who owns it, how fresh is it, and where does its source truth live? The fourth is a link to the canonical path here, not a paraphrase of it.

Promotion. A wiki page cited twice, or referenced by any standard, must be promoted into BluCity-Docs under §3.2 or deleted. The wiki is where knowledge starts or dies, never where it settles.

8.4 Publication — Git authors, other surfaces serve

Git is the authoring authority and the evergreen source of record. Other surfaces are derived: they publish, index and deliver what is authored here. Authority never moves downstream, and nothing downstream is a place to write doctrine.

          BluCity-Docs (Git)          canonical · versioned · reviewable · diffable
                   │
        publish / index / curate
          ┌────────┴─────────┐
          │                  │
   ContextControl      Gemini Notebook
   governed            research and
   operational         synthesis surface
   context
          └────────┬─────────┘
                   │
                AGENTS  ← narrow task context, disposable session
  • ContextControl owns selection, scope, provenance, approval and lifecycle of context delivered to agents. It does not own the text.
  • Gemini Notebook is a source-grounded research mirror for cross-document interrogation. Its output is not authority. A durable conclusion travels: notebook research → evidence in ledger/ → review → the owning document here → republication.

8.5 The ingestion contract

Ingestion needs no new metadata. The front matter §2 and STD-033 already require is the contract: bluefly_document, type, status, authority, owner, canonical_path, supersedes / superseded_by, created_at, updated_at, last_reviewed.

Precedence when serving: canonical > evergreen > everything else. A document with status: snapshot or superseded is never served as current — it is retrievable as history only. The wiki and .agents/context/ may be ingested as context; neither is ever ingested as authority.

A retrieval request is scoped by agent, project and Bead, and the answer names what is required, what is optional, and what is out of scope — with provenance and last_reviewed on every item. Returning the corpus is a defect, not a safe default: an agent that loads the whole estate has made the conversation its database, which §6 "Agent context budget" already prohibits.

NOT_ESTABLISHED: ContextControl has no running instance at the time of writing (bc-7e3 is still provisioning its Cloudflare tunnel). §8.4–§8.5 are written to be satisfiable on arrival and depend on nothing that does not already exist in this repository.