From 0f45f19523ea686f93bea752f099f61dfde03bee Mon Sep 17 00:00:00 2001 From: forkwright Date: Mon, 17 Aug 2026 14:42:47 -0500 Subject: [PATCH 1/2] fix(docs): remove the internal forge hostname and add the doc manifest Two pre-existing lint errors made this repo's main un-gateable, so no branch could reach green regardless of its own quality. Found while gating unrelated work. CONTRIBUTING.md carried an internal .lan hostname in three places -- the forge's address written into tracked content. That address is per-box state, not a property of this repository, so it is now referred to as with a note saying where a reader gets the real value: their own git remote, or the kanon MCP binding the session-start probe reports. Removing a fact without saying where it lives would just move the problem. This matters beyond the lint: an internal hostname in a tracked tree is exactly the class of content that must not survive into a public repository, and this repo is in scope for the fleet's public-flip work. docs/MANIFEST.toml did not exist while docs/ did. Seven entries, one per document, classified by reading each rather than by pattern: two decision records, four authored, and the mesh config example. Three are marked non-evergreen with the reason stated in place -- the lexicon calls itself a living registry, the reference-store doc describes an arrangement built on a crate that is still planned, and the config example is a snapshot of supported hardware. The archive subtree is deliberately absent. Git is the archive, and a second index of superseded documents is a copy of what history already guarantees. --- CONTRIBUTING.md | 10 ++++++--- docs/MANIFEST.toml | 56 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 63 insertions(+), 3 deletions(-) create mode 100644 docs/MANIFEST.toml diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cff15bb..fc22897 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,17 +5,21 @@ Akroasis is a Rust workspace for multi-domain signal intelligence - radio, mesh, ## Push target ``` -origin = http://kanon.lan/forkwright/akroasis.git (authoritative) +origin = /forkwright/akroasis.git (authoritative) github = git@github.com:forkwright/akroasis.git (mirror) ``` +`` is this box's forge address. It is per-box state, not a property of this repository, so +it is not written down here — read it from your own `git remote -v`, or from the kanon MCP +binding that the session-start topology probe reports. + Push to `origin`. The forge post-receive hook runs CI (`.kanon-ci.toml`) and mirrors merge commits to GitHub via the pr-sync worker. ## Opening a PR Two paths, same effect: -**Stoa UI.** Open `http://kanon.lan/prs/forkwright/akroasis`, click "New PR", pick base + head refs, review diff, submit. +**Stoa UI.** Open `/prs/forkwright/akroasis`, click "New PR", pick base + head refs, review diff, submit. **CLI.** @@ -50,7 +54,7 @@ The GitHub mirror at `github.com/forkwright/akroasis` works as before. A PR open ## Fallback -If the forge is unreachable, push to `github` and open a GitHub PR. When the forge is back, its pr-sync worker picks up the PR and continues from there. This is an escape hatch, not a preferred path - use it only when kanon.lan is actually down. +If the forge is unreachable, push to `github` and open a GitHub PR. When the forge is back, its pr-sync worker picks up the PR and continues from there. This is an escape hatch, not a preferred path - use it only when the forge is actually down. ## CI configuration diff --git a/docs/MANIFEST.toml b/docs/MANIFEST.toml new file mode 100644 index 0000000..5f1b1cb --- /dev/null +++ b/docs/MANIFEST.toml @@ -0,0 +1,56 @@ +# docs/MANIFEST.toml +# Documentation inventory for akroasis. See standards/DOC-MANIFEST.md. +# +# WHY the archive/ subtree is absent rather than listed: git is the archive, and a second index of +# superseded documents is a copy of what history already guarantees — it grows with no signal because +# nobody maintains it. + +[[doc]] +path = "docs/ARCHITECTURE.md" +type = "authored" +evergreen = true +description = "Five-layer structure and the shared typed-signal pipeline every domain feeds." + +[[doc]] +path = "docs/PROJECT.md" +type = "authored" +evergreen = true +description = "What akroasis is: the capability domains unified by one shared signal model." + +# WHY not evergreen: it names itself a living registry that changes as crates are added or renamed, so +# its content is a snapshot of the crate set rather than a timeless statement. +[[doc]] +path = "docs/lexicon.md" +type = "authored" +evergreen = false +description = "Registry of akroasis crate names and the concept each one owns." + +# WHY not evergreen: describes a store owned through a crate that is still planned, so it states an +# intended arrangement rather than one a reader can currently observe. +[[doc]] +path = "docs/reference-store.md" +type = "authored" +evergreen = false +description = "Layout of the long-term offline reference store and its ownership boundary." + +[[doc]] +path = "docs/fjall-column-encryption.md" +type = "decision-record" +evergreen = true +description = "Where the encryption boundary sits for fjall-backed columns, and what is left declarative." +decided = "2026-08-17" + +[[doc]] +path = "docs/pq-content-key-wrapping.md" +type = "decision-record" +evergreen = true +description = "Post-quantum content-key wrapping for multi-device key distribution." +decided = "2026-08-17" + +# WHY authored and not generated: it is a hand-written example config a reader copies from, not output +# any command reproduces — a generate_cmd here would be a claim nobody could run. +[[doc]] +path = "docs/akroasis-mesh.toml" +type = "authored" +evergreen = false +description = "Example mesh configuration section, with the supported hardware and transports." From 5d37f5b5976b4c743a6dee50cdcac048b9416d50 Mon Sep 17 00:00:00 2001 From: forkwright Date: Mon, 17 Aug 2026 14:53:33 -0500 Subject: [PATCH 2/2] docs: list the archive subtree so the orphan check can account for it The first version deliberately omitted docs/archive/ on the reasoning that git is the archive and a second index of superseded documents duplicates what history already guarantees. That reasoning is right in general and answers a different question than the rule asks. STANDARDS/doc-manifest-orphan asks only whether every file under docs/ is accounted for, because an unlisted file is indistinguishable from one nobody noticed. Listing the two archived documents as non-evergreen answers that without claiming they are current. --- docs/MANIFEST.toml | 25 ++++++++++++++++++++++--- 1 file changed, 22 insertions(+), 3 deletions(-) diff --git a/docs/MANIFEST.toml b/docs/MANIFEST.toml index 5f1b1cb..697feec 100644 --- a/docs/MANIFEST.toml +++ b/docs/MANIFEST.toml @@ -1,9 +1,12 @@ # docs/MANIFEST.toml # Documentation inventory for akroasis. See standards/DOC-MANIFEST.md. # -# WHY the archive/ subtree is absent rather than listed: git is the archive, and a second index of -# superseded documents is a copy of what history already guarantees — it grows with no signal because -# nobody maintains it. +# The archive/ subtree IS listed, and the reasoning that first left it out is worth recording because +# it was right in principle and wrong here. Git is the archive, so a second index of superseded +# documents duplicates what history already guarantees. But `STANDARDS/doc-manifest-orphan` asks a +# narrower question — is every file under docs/ accounted for — and an unlisted file is +# indistinguishable from one nobody noticed. Listing them as superseded answers that without +# pretending they are current. [[doc]] path = "docs/ARCHITECTURE.md" @@ -54,3 +57,19 @@ path = "docs/akroasis-mesh.toml" type = "authored" evergreen = false description = "Example mesh configuration section, with the supported hardware and transports." + +# ── superseded ──────────────────────────────────────────────────────────────────────────────────── +# Listed so the orphan check can account for them, marked non-evergreen because that is what +# superseded means. Neither is a current statement about this repository. + +[[doc]] +path = "docs/archive/README.md" +type = "authored" +evergreen = false +description = "Index of completed or superseded documentation kept for historical reference." + +[[doc]] +path = "docs/archive/STANDARDS.md" +type = "authored" +evergreen = false +description = "Superseded project standards, retained as the record of what the rules used to be."