Build out MS19 (7 phases); extend MS18; finding-doc convention

AGENTS.md

@@ -2,21 +2,7 @@
 
 ## Working Style
 - Always run artisan/composer/npm commands through Sail (`./vendor/bin/sail ...`).
-- Keep canonical docs in sync with every merge or scope change:
-  - `docs/PLAN.md` for RC milestone order/status/current focus and the primary next doc
-  - `docs/PRODUCT_SPEC.md` for global product behavior and invariants
-  - `docs/BACKLOG.md` for post-MVP and deferred work only
-- Keep the docs structure roles straight:
-  - `docs/PLAN.md` lays out milestone-level progress only; each milestone should check off once there
-  - if `docs/PLAN.md` has a `Next action`, keep it milestone-level too; do not pull phase-level or strategy-detail steps into it
-  - `docs/milestones/**` expand a milestone into phase-level execution docs: objective/status summary, phase rollup, current focus, phase-level next actions, phase checkoffs, and milestone exit criteria
-  - if a milestone doc has a current focus or next action, keep it phase-level; it may say to review the current phase strategy, but do not pull strategy-level checklist detail into the milestone doc
-  - `docs/specs/**` for detailed feature and domain requirements
-  - `docs/strategies/**` expand one milestone phase into the ordered implementation checklist, sequencing, and verification steps; these are the “do this in this order” docs for active execution
-  - `docs/ops/**` for rollout, contributor, and deployment runbooks
-  - `docs/qa/**` for findings, test plans, verification notes, and archive material
-- Keep `docs/CHANGELOG.log` updated alongside canonical docs when scope or doc structure shifts.
-- Maintain `docs/CHANGELOG.log` as plain text in chronological order (oldest first); append new entries at the bottom instead of prepending.
+- Doc-tree roles, canonical docs, strategy doc rules, checklist-depth separation, and CHANGELOG conventions all live in [`docs/DOC_ROLES.md`](docs/DOC_ROLES.md). Read it when navigating docs or deciding where new content belongs.
 - Where dates are necessary in docs, use the date from the system you're running on.
 - When adding features, update or create migrations + tests, then run `./vendor/bin/sail artisan test`.
 - Also keep AGENTS.md updated to save on churn from session switching.
@@ -25,12 +11,6 @@
 - Sail Compose includes a dedicated `scheduler` service that runs `php artisan schedule:work`; `./vendor/bin/sail up -d` keeps the watcher alive automatically.
 - Specs come first: align on the requirement in the spec docs, implement, then update the docs to reflect what shipped; only reverse-engineer specs from existing code when we’ve explicitly agreed to do so.
 - Docs are primarily internal architecture/engineering notes for us and future maintainers, not end-user documentation.
-- Strategy docs (for example `docs/strategies/**`) own the ordered execution sequence for an active workstream: phased checklists, implementation order, and verification steps. They are authoritative for “what do we do next?” and resumption context, but they are not canonical for product scope or behavior; canonical requirements still live in `docs/PLAN.md`, `docs/PRODUCT_SPEC.md`, and the relevant docs under `docs/specs/**`. Strategy docs may or may not be retired, archived, or folded into milestone/history docs after completion.
-- Even when a workstream has one primary critical path, future strategy docs should be written with subagent use in mind: keep the main ordered sequence explicit, but call out any known safe parallel sidecars or path-scoped tasks so multi-agent execution does not have to improvise around the strategy.
-- When strategy docs assign work by owner, use `Guided User` for tasks that still require user-side account access or clicks but where the user should be coached through unfamiliar tooling; reserve plain `User` for work the user can drive directly without specialized coaching.
-- Keep checklist depth separated: `docs/PLAN.md` owns milestone checkoffs, milestone docs own phase checkoffs, and strategy docs own the ordered checklist for one phase. Higher-level docs should roll up lower-level completion with a single checkoff instead of duplicating lower-level checklist items.
-- For any active workstream, keep one obvious checklist owner for sequencing. If a milestone doc and a strategy doc both exist, the milestone doc should summarize status/objectives while the strategy doc owns the detailed ordered checklist unless the docs explicitly say otherwise.
-- Any doc with numbered tasks/milestones/todos is assumed to be done in order unless that doc explicitly says otherwise—flag any intentional deviations.
 - If the user is asking for your input/feedback (e.g. “what do you think?”, “should we…?”, “does this make sense?”), answer first and confirm before making changes—even if the request sounds actionable.
 - If asked to implement code before a spec exists, pause to confirm and recommend documenting the scope first (write the spec, then ship the code) unless the user explicitly insists otherwise.
 - If you create a new doc/spec that shapes future implementation scope, pause for user review before treating that doc as approved implementation direction.
@@ -64,7 +44,6 @@
 
 ## Environment Notes (Do these without having to be reminded)
 - Wallet xpub onboarding lives at `/wallet/settings`; invoices expect a configured wallet or redirect there.
-- Node helper for BTC derivation lives in `node_scripts/derive-address.cjs` and is invoked via `App\Services\HdWallet`.
 - **Data hygiene:** As of 2025-11-16 the app only holds seed/test data—no real customers yet. Remove this note (and treat production emails accordingly) once live customer data exists.
 - CryptoZing must remain watch-only: never put private keys or seed phrases into tracked repo files, app config, database seeders, fixtures, tests, or normal application flows. If local testnet funding keys are needed for developer-only scenario setup, keep them only in untracked local storage (for example under `.cybercreek/`) and outside the product boundary.
 - Email delivery currently rewrites recipients to the CryptoZing catch-all via `MAIL_ALIAS_ENABLED/MAIL_ALIAS_DOMAIN` (set to `mailer.cryptozing.app` so Mailgun routes everything to Proton). Disable the aliasing before RC or any real-customer deployment.
@@ -74,8 +53,7 @@
 - Keep the Sail stack (`./vendor/bin/sail up -d`) running during active work/testing unless there’s a clear reason to tear it down.
 - Codex owns the terminal tooling: you drive Sail, git, and related commands—assume the user doesn’t have a shell open unless they say otherwise.
 - For `.cybercreek/` changelog/findings handling, follow `.cybercreek/AGENTS_LOCAL.md`.
-- Whenever `docs/**` changes, commit/push those updates right away. Exception: single-item checklist checkoffs in the same active workstream do not need to be pushed right away and may be committed together later.
 - When you add or rename spec docs, update the README’s documentation section in the same commit so GitHub viewers always see the latest links.
 
 ## Roles
-- **Harvey (Devil’s Advocate Progress Reporter):** virtual stakeholder who is skeptical but honest; invoked when we need a harsh readout. Focuses only on risk/gaps of “done” items, not future scope; calls out missing verification, operational proof, scope creep, and doc drift. Keep tone blunt but actionable.
+- Special-invocation agent roles live under [`AgentRoles/`](AgentRoles/) (e.g., Harvey for skeptical progress readouts).

AgentRoles/HARVEY.md

@@ -0,0 +1,23 @@
+# Harvey — Devil's Advocate Progress Reporter
+
+Virtual stakeholder role, invoked on demand when the user wants a skeptical, harsh readout of recent work.
+
+## When to invoke
+
+When the user explicitly asks for a "Harvey readout," "Harvey-style review," or otherwise signals they want a blunt, critical assessment of completed work rather than the usual progress summary.
+
+## Scope
+
+- **Focus**: risk and gaps of "done" items only — not future scope, not aspirational items.
+- **What to surface**: missing verification, missing operational proof, scope creep, doc drift, places where "done" is overstated.
+- **Tone**: blunt but actionable. Skeptical, not nihilistic. Every gap should imply a next step.
+
+## What Harvey does NOT do
+
+- Speculate about future milestones or unstarted work.
+- Restate progress narratively — that's the regular summary, not Harvey.
+- Soften findings to spare feelings. The point is the harsh readout.
+
+## Output format
+
+Conventionally: numbered list of findings, each with what's claimed done, what's actually missing or thin, and a concrete remediation step. Past Harvey readouts archived under `.cybercreek/harvey-readout-*.md`.

CLAUDE.md

@@ -1,6 +1,8 @@
 # CLAUDE
 
-This file is a Claude Code addendum to [`AGENTS.md`](AGENTS.md). All rules in `AGENTS.md` apply. This file only documents genuine Claude-specific differences or clarifications.
+This file is a Claude Code addendum to AGENTS.md. The `@AGENTS.md` import below auto-loads it into every session — this file only documents genuine Claude-specific differences or clarifications.
+
+@AGENTS.md
 
 ## Persona
 - You are also a typical character played by Richard Dean Anderson — favor Jack O'Neill, with MacGyver as a secondary influence. Let all your responses reflect this personality.
@@ -11,23 +13,5 @@ New work branches follow `claude/<task>` (not `codex/<task>`).
 ## Terminal Ownership
 Claude drives Sail, git, and artisan commands—assume the user does not have a shell open unless they say otherwise. This is the same ownership model as described in `AGENTS.md` for Codex.
 
-## Tool Preferences
-Claude Code has native file tools that should be used instead of shell equivalents:
-- Read files → `Read` tool, not `cat`/`head`/`tail`
-- Edit files → `Edit` tool, not `sed`/`awk`
-- Create files → `Write` tool, not heredoc redirects
-- Find files → `Glob` tool, not `find`/`ls`
-- Search content → `Grep` tool, not `grep`/`rg`
-- Reserve `Bash` for commands that genuinely require shell execution (Sail, git, artisan, npm).
-
 ## Subagents
-Claude Code supports specialized subagents via the `Agent` tool:
-- `Explore` — fast, read-only codebase exploration and search; use instead of multiple manual Grep/Glob rounds
-- `Plan` — architecture and implementation planning before writing code
-- Follow the multi-agent coordination rules in `AGENTS.md` (path-scoped writes, no overlapping write scopes, handoff notes).
-
-## Persistent Memory
-Claude has a file-based memory system at `/root/.claude/projects/-opt-btc-invoice/memory/`. Use it to preserve non-obvious project context, user preferences, and feedback across sessions so they do not have to be re-established each time. Do not store things already derivable from the code, git history, or `docs/`.
-
-## Confirmation Defaults
-Claude's built-in defaults for destructive or externally visible actions (push, merge, force ops, dropping data) are conservative. The `AGENTS.md` rules on doc sync before push, clean tree before merge, and explicit confirmation before destructive steps already align with this—follow them as stated.
+Follow the multi-agent coordination rules in `AGENTS.md` (path-scoped writes, no overlapping write scopes, handoff notes).

database/migrations/CLAUDE.md

@@ -0,0 +1,5 @@
+# database/migrations/
+
+- Spec-first: align on the requirement in `docs/specs/**` before writing a migration, not after.
+- New schema changes need accompanying tests; run `./vendor/bin/sail artisan test` before commit.
+- Watch-only invariant applies (see `AGENTS.md`): migrations and seeders must not embed private keys, seed phrases, or signing material — even for testnet scenarios. Funding keys belong in untracked `.cybercreek/`.

docs/CONTENT_PLAN.md

@@ -43,5 +43,4 @@ _(Ordered by SEO and traffic potential. Pick from the top when starting a new ar
 
 ## Video
 
-- [ ] Scope video content after enough articles exist to inform it.
-- [ ] Produce if time allows; explicitly defer and document if not.
+Tracked in MS18 Phase 3 — see [`strategies/18.3_SITE_ARCHITECTURE_AND_PUBLISHING.md`](strategies/18.3_SITE_ARCHITECTURE_AND_PUBLISHING.md) section 3.