docs(miner): document all sixteen local SQLite stores in DEPLOYMENT.md (#4870)

[carlh7777]

Summary

packages/gittensory-miner/DEPLOYMENT.md's "expected layout" section listed only 5 of the miner's local SQLite stores (claim-ledger, plan-store, portfolio-queue, event-ledger, governor-ledger), but the package actually creates 16. An operator following the doc would miss most of their own on-disk state — the exact problem #4870 reports.

This rewrites the layout to list every store the package creates, each with its filename, a one-line purpose, and its issue ref:

• laptop-state (init state), portfolio-queue (feat(miner-foundation): local portfolio/queue store for gittensory-miner #2292), claim-ledger (feat(miner-foundation): local claim-ledger SQLite schema + CRUD in packages/gittensory-miner #2314), plan-store (feat(miner-foundation): local SQLite persistence adapter for the stateless MCP plan DAG #2318), run-state, event-ledger (feat(miner-foundation): immutable event ledger for gittensory-miner #2290), governor-ledger (feat(miner-governor): append-only local event ledger schema + writer #2328), governor-state (Persist governor cross-attempt state (rate-limit, budget, convergence, reputation, self-plagiarism) #5134),
• attempt-log (feat(miner-hands): driver-level structured attempt log (JSONL event trace per attempt) #4294), worktree-allocator (feat(miner-concurrency): add git-worktree-per-attempt allocator #4297), prediction-ledger (feat(miner-selfimprove): local prediction-ledger schema — record every predicted-gate verdict for later scoring #4263), replay-snapshot (feat(miner): freeze/snapshot mechanism for historical replay targets #3010), policy-doc-cache (Add conditional-GET caching for policy-doc fetches #4842), policy-verdict-cache (Add a persisted cross-invocation cache of resolved policy verdicts #4843), deny-hook-synthesis (feat(miner): synthesize PreToolUse deny-hook rules from the review stack's own per-repo close/blocker finding-category history #4522), orb-export (feat(miner-manage): optional anonymized Orb telemetry export for miner outcomes #4277).

It also adds two accuracy notes: files are created lazily (only once the relevant subsystem first runs, so a fresh status/doctor-only install shows a subset), and every store except laptop-state honors its own GITTENSORY_MINER_<NAME>_DB path override in addition to the directory-level GITTENSORY_MINER_CONFIG_DIR.

Every filename and env-var name was verified directly against the store modules in packages/gittensory-miner/lib (all 16 .sqlite3 defaults; none exist outside lib/), so the list is complete and exact.

Closes #4870

Scope

• The PR title follows type(scope): short summary Conventional Commit format.
• This PR is focused and does not mix unrelated backend, UI, MCP, docs, dependency, and deploy changes.
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• I linked a currently open issue this PR resolves (Closes Update DEPLOYMENT.md to document all local stores #4870).

Validation

• git diff --check
• npm run docs:drift-check (passes — the generated-docs drift check is unaffected)
• npm run typecheck / test:* / build:* / ui:* — N/A: single hand-written Markdown doc change, no code, schema, or generated artifact touched.
• Completeness verified by enumerating every *.sqlite3 default in packages/gittensory-miner/lib (16) and confirming none exist elsewhere in the package.

If any required check was skipped, explain why:

Documentation-only change to one Markdown file (DEPLOYMENT.md); it touches no source, tests, schemas, or generated artifacts, so the build/type/UI/coverage checks are N/A.

Safety

• No secrets, wallet details, hotkeys, coldkeys, PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed (only public store filenames + env-var names, all already in the source).
• Public GitHub text stays sanitized and low-noise.
• Auth/CORS/session negative-path tests — N/A.
• API/OpenAPI/MCP behavior updated/tested — N/A.
• UI changes use real states — N/A (no UI).
• Visible UI changes include UI Evidence — N/A (no UI; a Markdown doc).
• Public docs/changelogs updated where needed; changelogs are only edited for release-prep PRs — this is a docs accuracy fix, not a changelog edit.

UI Evidence

N/A — Markdown documentation change only.

Notes

• The layout is presented as the full set with a lazy-creation caveat rather than split into hard "created early / created later" buckets, since exactly when each file first appears depends on which subcommands an operator runs; the caveat keeps the doc accurate without over-claiming per-store timing.

[superagent-security]

🚨 Contributor flagged. Click here for more info: Superagent Dashboard

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[loopover-orb]

Tip

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-13 04:02:35 UTC}

1 file · 1 AI reviewer · no blockers · readiness 100/100 · CI green · unstable

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This is a pure documentation update to DEPLOYMENT.md that expands the 'expected layout' listing from 5 to 16 SQLite stores, adding filenames, purposes, and issue references, plus two accuracy notes about lazy file creation and per-store env-var overrides. The change is docs-only, closes the linked issue #4870 directly, and the content reads as internally consistent (each store name maps to a plausible subsystem and issue number), though I cannot independently verify every filename/env-var against the actual store modules in packages/gittensory-miner/lib since those files aren't in the provided diff or context. No code paths are touched, so there's no correctness or wiring risk.

Nits — 5 non-blocking

• The claim that filenames and env-var names were 'verified directly against the store modules' can't be checked from this diff alone — worth a spot-check that GITTENSORY_MINER_PORTFOLIO_QUEUE_DB and the other 14 env-var names actually match the store modules' naming convention, not just the pattern implied by portfolio-queue.sqlite3.
• The doc doesn't clarify whether store filenames use hyphens consistently in both the file and the env var (e.g. deny-hook-synthesis.sqlite3 vs an env var that would presumably be GITTENSORY_MINER_DENY_HOOK_SYNTHESIS_DB) — a one-line note or second example would remove any ambiguity for operators with multi-word store names.
• Consider linking each `#NNNN` issue reference as a markdown link (as done elsewhere in this same file, e.g. `[Write an operational runbook #4875](...)`) for consistency with the rest of DEPLOYMENT.md rather than bare `#NNNN` text.
• If `doctor`'s `store-integrity:*` output already names each store, cross-reference that command's exact output format here so operators can grep for a name and get an exact match.
• nit: packages/gittensory-miner/DEPLOYMENT.md:59 describes `XDG_CONFIG_HOME` as overriding the directory for every store, but `XDG_CONFIG_HOME` is usually a base config directory rather than the final miner state directory, so this should be worded more precisely to avoid operators pointing it at the wrong path.

Flagged checks (non-blocking)

• Contributor trust — Contributor flagged for review

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#4870
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 190 registered-repo PR(s), 120 merged, 17 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	carlh7777; Gittensor profile; 190 PR(s), 17 issue(s).
Gate result	✅ Passing	No configured blocker found.
Improvement	⚠️ ℹ️ Insufficient signal	risk: clean · value: insufficient-signal — Nothing measurable for the structural-improvement analyzers on this PR (e.g. no code files changed).

Review context

• Author: carlh7777
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: Python, JavaScript, TypeScript, Cuda, HTML, MDX, Rust
• Official Gittensor activity: 190 PR(s), 17 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Keep the PR focused and include validation evidence before maintainer review.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

[BETA] Chat with Gittensory

Ask Gittensory a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @gittensory ask <question> answers contribution-quality Q&A with source citations and freshness.
• @gittensory chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @gittensory mention with a real question is routed to the closest matching read-only command automatically -- no exact syntax required.

Full command reference: https://gittensory.aethereal.dev/docs/gittensory-commands

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review

[loopover-orb]

Gittensory approves — the gate is satisfied and CI is green.