AGENTS.md (Technical)

NutsNews repository-wide contribution contract for documentation.

Visual overview

Primary diagram

System map

A contribution is classified as manual documentation, merge-triggered documentation, or site-code work. Manual documentation receives human review. The merge workflow gives Codex no write token, rejects prohibited paths, records immutable merge provenance, and publishes only a complete validated bundle. Site-code or mixed work uses a checked and approved pull request.

Render the repository-owned system map when you need it.

Diagram is not rendered yet.

View as text

AGENTS.md (Technical)

---
title: AGENTS migration governance flow
---

flowchart TD
  accTitle: AGENTS.md (Technical)
  accDescr {
    A contribution is classified as manual documentation, merge-triggered documentation, or site-code work. Manual documentation receives human review. The merge workflow gives Codex no write token, rejects prohibited paths, records immutable merge provenance, and publishes only a complete validated bundle. Site-code or mixed work uses a checked and approved pull request.
  }
  request["Contribution request"] --> automated{"Trusted merged-PR workflow?"}
  automated -->|Yes| codex["Codex drafts complete bundle without GitHub write access"]
  codex --> boundary{"Only allowed documentation paths changed?"}
  boundary -->|No| incident["Block publication and report failure"]
  boundary -->|Yes| provenance["Record repository, PRs, merge SHA, run, and source hash"]
  provenance --> validate["Run exact wiki validation commands"]
  automated -->|No| classify{"Documentation only?"}
  classify -->|Yes| bundle["Update canonical source, Simple mirror, Technical mirror, and diagram"]
  bundle --> review["Human reviews current Simple content and diagram"]
  review --> approve["Record current approval"]
  approve --> validate
  validate --> direct["Commit and push directly to main"]
  classify -->|No or mixed| branch["Create site-code branch"]
  branch --> pr["Open normal ready pull request"]
  pr --> checks["Require passing checks and explicit merge approval"]
  checks --> publish["Merge and publish"]
  direct --> publish

AGENTS.md (Simple)

What this repo is

This repository is the main home for NutsNews documentation.
The original Technical documents live at the root or in archive/, ios/, reports/, and updates/.
Every original document has a Simple copy, a Technical copy, and a Mermaid diagram in the matching audiences/ and diagrams/ paths.

Which workflow to use

Documentation-only changes may go directly to main after all wiki checks pass.
The protected merge-documentation workflow may automatically publish a complete documentation-only update after a NutsNews pull request is merged and every safety check passes.
Changes to the site, tests, tools, dependencies, configuration, or GitHub Actions need a branch, a normal pull request, passing checks, and explicit approval before merge.
A change that mixes docs and site code uses the pull-request workflow.

Keep the complete document set current

Update the original document, its Simple copy, its Technical copy, and its accessible diagram together.
A real content change makes the old approval stale. Normal authoring requires human review. The merge workflow is the only automatic exception: Codex drafts the bundle without write access, then trusted checks record the repository, PR, merge commit, workflow run, and source hash.
Codex cannot commit, push, or change workflows. Any unrelated file change blocks publication.
Do not edit generated site files, test output, caches, or the generated inventory.

Exact commands

For a new document:

npm run docs:new -- <canonical-source.md> --collection <collection> --section <section>
npm run docs:prepare -- <canonical-source.md> --force

Use --force only for the blocked bundle just created by docs:new, not to replace unrelated existing work.

After human review:

npm run docs:approve -- <canonical-source.md> --reviewed-by "<human-reviewer>" --confirm-human-review

The separate docs:auto-approve command belongs only to the trusted merge workflow and is not a shortcut for manual work.

Before a documentation-only commit:

npm run wiki:prepare
npm run validate:content
npm run validate:links
npm run validate:mermaid
npm run test:content-routes
npm run build

Keep secrets and local environment files out of documents and generated artifacts. Preserve unrelated work and every existing safety boundary.