From 6cc9fe009cf8f790aae9609afd0a05aa1205e628 Mon Sep 17 00:00:00 2001
From: null <koga.industries@gmail.com>
Date: Tue, 18 Aug 2026 00:07:28 -0500
Subject: [PATCH] docs: two start-here documents, one per kind of adoption

Two kinds of project arrive at this template and neither had a document written
for it. A new repository needs a first act. An existing one -- which is most of
them, since eight were surveyed and one had adopted anything -- needs a merge,
with documents and conventions already in place that must survive it.

What existed was README's "Adopting it": seven steps aimed at a person reading
top to bottom, silent about existing projects, and opening with the one form
that destroys work:

    cp -r Projects/Template/docs <your-project>/docs

cp -r overwrites. scaffold.sh exists precisely because that is unsafe, and its
header argues the case at length: a clobbered document is work nothing notices
is gone, silent when it happens and silent afterwards. An existing project
following step 1 literally replaced its own architecture notes with
placeholders. The instruction and the tool disagreed and the instruction was the
dangerous one.

Both documents hold one prompt each, written to be handed to an agent whole, and
both open by putting it in PLAN MODE with nothing changed until the plan is
approved. Each plan must name what will be created, what kept, what deleted,
which scripts the project adopts -- and what will be left undone, by name. That
last is the one that gets skipped: an adoption quietly missing the webhook or
half the status headers looks identical to a complete one from outside.

The existing-project prompt is the harder half. Its spine is survey, reconcile,
destroy nothing: the survey IS the plan phase and is entirely read-only; the
scaffold's "kept" list is the merge worklist; existing prose is the project's own
knowledge and the template supplies shape, not content; and any markdown backlog
moves into the tracker and is deleted in the same commit, because two records of
what is open is the failure the whole convention exists to prevent.

Verified rather than asserted, since the whole document rests on it: a scratch
project with three written documents, scaffolded into, reported 16 created and 3
kept, and all three pre-existing files were byte-identical afterwards with their
prose intact.

README's section becomes a pointer to the two, since three descriptions of
adoption in one repository is the two-records failure with an extra copy, and the
sentence about the Command Center's generated prompt now says which is the
source rather than leaving a reader to pick.

Also corrected: README's `Governs: Projects/Template/**` was true when this was a
folder inside Projects/ and matched nothing once it became a repository root.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 README.md                      |  48 +++++------
 START-HERE-Existing-Project.md | 137 +++++++++++++++++++++++++++++++
 START-HERE-New-Project.md      | 146 +++++++++++++++++++++++++++++++++
 3 files changed, 308 insertions(+), 23 deletions(-)
 create mode 100644 START-HERE-Existing-Project.md
 create mode 100644 START-HERE-New-Project.md

diff --git a/README.md b/README.md
index 9b58abb..15d6c85 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@ create the labels and the first milestone in the repository's issue tracker.
 Status: Current
 Owner: _null
 Last reviewed: 2026-08-12
-Governs: Projects/Template/**
+Governs: README.md, START-HERE-New-Project.md, START-HERE-Existing-Project.md
 Review trigger: Any change to the tracker conventions or the QA run-state
                 grammar in the Privacy LLC Command Center's src/lib/; any
                 change to which project fields the agent API can write, or to
@@ -272,26 +272,28 @@ passes — is the one that costs thirty seconds and catches the rest.
 
 ## Adopting it
 
-1. `cp -r Projects/Template/docs <your-project>/docs`
-2. Fill in the status header on each file — especially **Review trigger**, which
-   is the line that keeps a document from going quietly stale.
-3. Create the four labels, one milestone, and an issue per deliverable you can
-   actually see ahead of you — in the tracker named above, not whichever one the
-   host happens to offer.
-4. Point git at the hooks: `cp docs/architecture/githooks/{pre-commit,commit-msg,post-commit} .githooks/ && chmod +x .githooks/* && git config core.hooksPath .githooks`. It is per-clone, so every checkout runs it once.
-5. Run `bash docs/architecture/scripts/check-env.sh` and `bash docs/architecture/scripts/secrets.sh --tracked` — the first says what is not configured, the second is the one-time audit for what is already committed.
-6. Map the repository on the project's edit screen in the Command Center, then
-   press **Pull**. One thing does not follow from mapping it and is silent when
-   missing: **register the repository's webhook** and confirm a delivery
-   arrives. Without one the site sees this repository only through the periodic
-   sweep — the counts still arrive, a day late, and an opened `P0` raises no
-   alert at all.
-7. Skim `docs/TOOLS.md` — the fixed path every project has, saying which
-   scripts can stop you and where to start in a fresh clone. Then read
-   `docs/WORK_CYCLE.md` once, now rather than at the end of the first
-   session. It is what happens every time a piece of work finishes, and the two
-   steps it exists for — recording the next action and the blockers, and telling
-   the site what changed — are the two that are invisible when they are skipped.
+Two documents, because the two jobs are different in the only way that matters —
+whether anything can be destroyed on the way in. Each holds one prompt, written
+to be handed to an agent whole:
 
-There is also a generated prompt for doing all of this with an agent, on the
-Docs template screen of the Command Center — editable before you copy it.
+| Starting from | Read |
+| --- | --- |
+| an empty repository | **[Brand New Project — Start Here](START-HERE-New-Project.md)** |
+| a repository that already has documents, a tracker, or conventions | **[Existing Project — Start Here](START-HERE-Existing-Project.md)** |
+
+Both begin by putting the agent in plan mode and require it to say what it will
+create, what it will keep, what it will delete and **what it will leave undone**,
+before it touches anything. An adoption that quietly skips the webhook or half
+the status headers looks identical to a complete one from outside.
+
+The mechanism in both is `docs/architecture/scripts/scaffold.sh`, and the
+important thing about it is what it refuses to do: it never overwrites a file
+that is already there. Do not adopt this template with `cp -r` — a scaffold that
+clobbers a written document destroys work nothing would notice was gone, and
+`cp -r` has no such protection.
+
+The Command Center's Docs template screen also generates an adoption prompt,
+editable before you copy it. **These two documents are the source.** That screen
+is a convenience and a separate copy, so where the two disagree the files here
+are the ones kept in step with the scripts they invoke — and a difference between
+them is worth reporting rather than picking a side.
diff --git a/START-HERE-Existing-Project.md b/START-HERE-Existing-Project.md
new file mode 100644
index 0000000..c87082d
--- /dev/null
+++ b/START-HERE-Existing-Project.md
@@ -0,0 +1,137 @@
+# Existing Project — Start Here
+
+```
+Status: Current
+Owner: _null
+Last reviewed: 2026-08-18
+Governs: how a project that already has documents and a tracker merges this template in
+Review trigger: Any change to scaffold.sh's never-overwrite behaviour; any change
+  to the tracker conventions, the labels, or the status header fields
+```
+
+There are two of these documents. This one is for a repository that **already has
+work in it** — documents, a tracker, conventions of its own, however partial. If
+the repository is empty, use [Brand New Project — Start
+Here](START-HERE-New-Project.md), which is a shorter and easier job.
+
+The difference is not cosmetic. Adopting into an existing project is a **merge**,
+and the failure it must not commit is destroying writing that nothing would
+notice was gone: no test fails for an architecture note that used to say more,
+there is no build to break, and if the file was never committed there is not even
+a diff to read. It is silent when it happens and silent afterwards.
+
+Hand the block below to an agent. It is written to be pasted whole.
+
+## The prompt
+
+```text
+Merge the project template at <TEMPLATE> into this repository, which already has
+work in it.
+
+FIRST: enter plan mode. Survey, and change NOTHING until the plan is approved.
+The survey is the plan — every step of it is read-only, and a merge proposed is a
+conversation while a merge performed is a diff somebody has to audit.
+
+THE SURVEY. Report what is actually here, changing nothing:
+
+  - Which of the template's documents already exist, under any name. A project
+    with ARCHITECTURE.md has an architecture document; it is not missing one.
+  - Whether a markdown backlog exists — TODO.md, ROADMAP.md, a batch ledger, a
+    checklist in the README. Name every file that lists work.
+  - The tracker: are the four labels present and spelled EXACTLY P0, P1, P2,
+    release-blocker? Any near-misses like p1 or "P1 - high"? How are milestones
+    named? How many issues sit outside any milestone?
+  - Which scripts already exist, and whether they overlap the template's.
+  - What README.md already claims about how this project works.
+
+Read <TEMPLATE>/docs/DOC_TRUST_MAP.md and <TEMPLATE>/docs/TOOLS.md before
+planning, so you know which document is supposed to own which answer.
+
+Your plan must name, separately:
+  - every file you will CREATE
+  - every existing file you will KEEP AND RECONCILE — a different risk, listed apart
+  - anything you will DELETE, and a migrated backlog above all
+  - which scripts this project will adopt, and which it will not
+  - what you will deliberately leave undone, by name, and why
+
+Once the plan is approved:
+
+1. SCAFFOLD, AND READ WHAT IT KEPT. The scaffold is the merge tool. It fills gaps
+   and reports every file that already exists as "kept", untouched, always:
+
+     SCAFFOLD_TEMPLATE_ROOT=<TEMPLATE> bash <TEMPLATE>/docs/architecture/scripts/scaffold.sh --dry-run --into .
+     SCAFFOLD_TEMPLATE_ROOT=<TEMPLATE> bash <TEMPLATE>/docs/architecture/scripts/scaffold.sh --into .
+
+   NEVER --force ON A PROJECT WITH REAL WRITING IN IT. That flag exists for a
+   tree scaffolded from a stale template and not yet written into. Here it
+   overwrites documents nothing will notice were lost.
+
+   NEVER `cp -r`. It has no such protection.
+
+   The "kept" list IS THE MERGE WORKLIST. Those files are the ones only a person
+   or a careful agent can reconcile.
+
+2. RECONCILE, DO NOT REPLACE. For each kept document: the existing prose is this
+   project's own knowledge and the template supplies shape, not content. Add the
+   status header — Status, Owner, Last reviewed, Governs, Review trigger, and
+   Fires on where it applies — to what is already written. Move content to the
+   document the trust map says owns it, and say in your report where each thing
+   went.
+
+   If an existing document says something that contradicts the template's version
+   of the same document, the EXISTING one is probably right about this project.
+   Ask rather than overwriting.
+
+3. MIGRATE ANY MARKDOWN BACKLOG INTO THE TRACKER, THEN DELETE THE MARKDOWN. This
+   is the single most valuable thing this merge does.
+
+   A list of open work in markdown beside a tracker holding the same work is two
+   records that will disagree, and nothing will say which is right. That has
+   already happened here: a tasks file drifted from the batch ledger and four
+   documents inherited a wrong batch number from it.
+
+   For each item: file an issue with a Verify: line, in a milestone. Then delete
+   the file IN THE SAME COMMIT as the issues being filed — a migration that
+   leaves the old copy in place has created the problem it was meant to solve.
+   Keep any reasoning worth keeping as narrative in docs/history/, which is a
+   record of then and cannot compete with a record of now.
+
+4. THE LABELS. Rename near-misses rather than adding duplicates — a repository
+   with both "P1" and "p1" has its defects split across two queries and reports
+   as not adopted. Exactly: P0, P1, P2, release-blocker.
+
+5. THE MILESTONES. Rename to the word-first form as you touch each one, not in a
+   sweep: "Batch 07 — Payments", not "0.7 Payments". A leading version token makes
+   the dashboard show only the version, and a comma in the title breaks the
+   milestones filter. Do not renumber history to make it tidy.
+
+6. WRITE docs/DOC_TRUST_MAP.md LAST, once everything else is settled, and describe
+   what is ACTUALLY HERE rather than what the template says should be. Its whole
+   value is being accurate about the others.
+
+   Where this project deliberately keeps a document out of git, declare it there
+   with an Exempt: line naming the real path. Note that those lines are read by a
+   checker: outside a code fence, an Exempt: line naming a real document is a live
+   declaration, not an example.
+
+7. THE REST OF ADOPTION is the same as a new project, and
+   START-HERE-New-Project.md has it in full: the hooks, check-env.sh,
+   secrets.sh --tracked, the branding issue rather than invented placeholders,
+   mapping on the Command Center and registering the webhook, and the first QA
+   run-state. Do not re-derive them from memory.
+
+FINALLY: report what you merged, where each thing went, and — separately and
+explicitly — WHAT YOU DID NOT MERGE AND WHY. A merge that silently drops
+something is worse than one that stops and asks, because the second is a question
+and the first is a loss nobody will discover.
+```
+
+## The three questions this usually raises
+
+- **"This project already has a document that does this job."** Keep it. Add the
+  header, and record in the trust map that it is the one that owns the subject.
+- **"There is a backlog in markdown."** It moves to the tracker and the file goes.
+  That is the whole point of the convention, and the one step people skip.
+- **"Some of the template does not apply."** Then delete it. A document that never
+  applied is noise; entries marked *(only for a deployed service)* and
+  *(only where money moves)* are there to be removed by projects they do not fit.
diff --git a/START-HERE-New-Project.md b/START-HERE-New-Project.md
new file mode 100644
index 0000000..7316d81
--- /dev/null
+++ b/START-HERE-New-Project.md
@@ -0,0 +1,146 @@
+# Brand New Project — Start Here
+
+```
+Status: Current
+Owner: _null
+Last reviewed: 2026-08-18
+Governs: how a brand-new project adopts this template, first run
+Review trigger: Any change to scaffold.sh's file list; any change to the tracker
+  conventions, the labels, or what the Command Center needs on adoption
+```
+
+There are two of these documents. This one is for a repository with **nothing in
+it yet**. If the project already has documents, a tracker, or conventions of its
+own, stop and use [Existing Project — Start Here](START-HERE-Existing-Project.md)
+instead — the two differ in the only way that matters, which is whether anything
+can be destroyed on the way in.
+
+Hand the block below to an agent. It is written to be pasted whole.
+
+## The prompt
+
+```text
+Adopt the project template at <TEMPLATE> into this repository.
+
+FIRST: enter plan mode and change nothing until the plan is approved.
+
+Your plan must name, specifically:
+  - every file you will create
+  - which scripts from the template this project will adopt, and which it will not
+  - the first milestone's name, and every issue you will file, each with its Verify: line
+  - anything you will delete
+  - what you will deliberately leave undone, by name, and why
+
+The last one is the point. An adoption that quietly skips the webhook, or the
+branding issue, or half the status headers, looks identical to a complete one
+from the outside. Say what you did not do.
+
+Read <TEMPLATE>/README.md and <TEMPLATE>/docs/TOOLS.md before planning. Read
+<TEMPLATE>/docs/WORK_CYCLE.md too: it is what happens at the end of every piece
+of work from now on, and knowing it changes what you set up now.
+
+Once the plan is approved:
+
+1. SCAFFOLD. Never `cp -r` — that overwrites, and the whole safety property of
+   the scaffold is that it does not:
+
+     SCAFFOLD_TEMPLATE_ROOT=<TEMPLATE> bash <TEMPLATE>/docs/architecture/scripts/scaffold.sh --dry-run --into .
+     SCAFFOLD_TEMPLATE_ROOT=<TEMPLATE> bash <TEMPLATE>/docs/architecture/scripts/scaffold.sh --into .
+
+   Read the report. "created" is what you got; "kept" means a file was already
+   there and was not touched; "skipped" is a failure, not a shrug.
+
+2. FILL THE STATUS HEADERS. Every document opens with one. The four status words
+   are exactly Current, Draft, Superseded and Archived — a checker reads them.
+   `Review trigger` is the line that matters, because "Last reviewed" ages on its
+   own and nothing notices.
+
+   NEVER INVENT A DATE. An unfilled header keeps asking; an invented one stops.
+   If you do not know when something was last reviewed, leave the placeholder.
+
+3. CHOOSE THE SCRIPTS, one at a time, having read each. The scaffold deliberately
+   copies none of them: an unconfigured release.sh landing in a new repository is
+   a loaded gun, not a head start. Copy what this project will actually use into
+   scripts/ and configure it before its first run.
+
+   docs/TOOLS.md explains that the table in docs/architecture/README.md is a menu
+   rather than an inventory. doc-claims will note the documents naming scripts you
+   did not take; that is expected and not a failure.
+
+   Record in your report which you took and which you declined.
+
+4. THE TRACKER. The four labels, spelled exactly: P0, P1, P2, release-blocker.
+   They are queried by name, and a mis-cased label reports the whole repository as
+   "not adopted" rather than as zero defects.
+
+   One milestone. Name it word-first with no comma — "Batch 01 — Foundations",
+   not "0.1 Foundations". A leading version token makes the dashboard show only
+   the version and drop the name, and a comma breaks the milestones filter so the
+   project card shows the wrong next action.
+
+   One issue per deliverable you can actually see ahead of you, each ending in a
+   Verify: line stating the acceptance check. DO NOT PAD. Every open issue is a
+   denominator, and invented future work makes every percentage wrong,
+   permanently and in one direction.
+
+   The template's own script enforces all of that and refuses malformed issues
+   before they are filed:
+
+     python3 <TEMPLATE>/docs/architecture/scripts/forgejo-issue.py --repo <owner/name> labels
+     python3 <TEMPLATE>/docs/architecture/scripts/forgejo-issue.py --repo <owner/name> batch issues.json --dry-run
+     python3 <TEMPLATE>/docs/architecture/scripts/forgejo-issue.py --repo <owner/name> check
+
+5. THE HOOKS. They live in the repository because .git/hooks is not versioned:
+
+     mkdir -p .githooks
+     cp docs/architecture/githooks/{pre-commit,commit-msg,post-commit} .githooks/
+     chmod +x .githooks/*
+     git config core.hooksPath .githooks
+
+   That last line is per clone, so every checkout runs it once. Say so in the
+   project README. Note that post-commit pushes.
+
+6. THE TWO AUDITS, before anything is trusted:
+
+     bash scripts/check-env.sh          # what is not configured, before something reads it
+     bash scripts/secrets.sh --tracked  # what is already committed
+
+   If the second finds something real: rotate it first. Deleting the line does
+   not remove it from a commit that already exists.
+
+7. BRANDING. docs/data/img/ needs icon.webp, logo.webp and banner.webp, checked
+   by magic bytes so a renamed PNG does not pass.
+
+   DO NOT GENERATE PLACEHOLDERS. This is the one gap in the convention an agent
+   cannot close. A placeholder that looks deliberate outlives the issue that
+   would have replaced it — nobody files a ticket against an image that appears
+   finished. File a P2 issue naming the three files and move on.
+
+8. THE COMMAND CENTER. Map the repository on the project's edit screen, then
+   press Pull. Then REGISTER THE REPOSITORY'S WEBHOOK and confirm a delivery
+   arrives. That does not follow from mapping it and is silent when missing:
+   without it the site sees this repository only through the periodic sweep, the
+   counts arrive a day late, and an opened P0 raises no alert at all.
+
+9. THE FIRST QA RUN-STATE. Fill docs/qa/ClaudeReport.md honestly. If no round has
+   been run, say exactly that. Its overall sentence is quoted verbatim on the
+   project screen, so write it as a sentence a stakeholder should read — not a
+   status word, and not a claim about testing that has not happened.
+
+10. FROM NOW ON, docs/WORK_CYCLE.md at the end of every piece of work: close what
+    you finished with the evidence, close the milestone if the batch landed,
+    update the documents the change triggered IN THE SAME COMMIT, push, log the
+    entry with Next action and Blockers, then reconcile and write the summary and
+    next action.
+
+FINALLY: report what you did, and separately, what you left undone and why.
+```
+
+## What you will be asked to decide
+
+Three things the agent cannot decide for you, and should stop and ask about:
+
+- **Which scripts this project adopts.** The answer is usually fewer than you
+  expect on day one, and more later.
+- **The first milestone and its issues.** Only you know what is actually ahead.
+- **The branding.** Three images somebody has to draw.