sanook-cli 0.5.1 → 0.5.2

package/second-brain/Projects/_Index.md

@@ -25,6 +25,8 @@ deliverable + overview/context/current-state ของ project
 
 > รายละเอียดทุกโฟลเดอร์ + decision rules → [[Vault Structure Map]]
 
-_(ยังว่าง — โน้ตในโฟลเดอร์นี้จะถูกลิงก์ที่นี่)_
+## Projects
+
+- [[Projects/sanook-cli/_Index]] — project workspace สำหรับ Sanook CLI
 
 up:: [[Home]]

package/second-brain/Projects/sanook-cli/_Index.md

@@ -0,0 +1,26 @@
+---
+tags: [index, moc, project, sanook-cli]
+note_type: moc
+created: 2026-06-18
+updated: 2026-06-18
+parent: "[[Projects/_Index]]"
+---
+
+# Sanook CLI
+
+> Project workspace for Sanook CLI product decisions, implementation plans, and current project-specific state. Use this for deliverables about the CLI itself, not generic second-brain theory.
+
+## Notes
+
+- [[Projects/sanook-cli/second-brain-feature-roadmap]] — roadmap for making second-brain features native to Sanook CLI
+
+## AI Routing Contract
+
+- ก่อนเขียน: ใช้โฟลเดอร์นี้เฉพาะงานที่เกี่ยวกับ Sanook CLI product/codebase โดยตรง
+- ก่อนสร้างไฟล์ใหม่: ค้นหา note เดิมใน `Projects/sanook-cli/` ก่อน เพื่อ merge/update แทน append ซ้ำ
+- เมื่อสร้างโน้ตในโฟลเดอร์นี้: ตั้ง `parent: "[[Projects/sanook-cli/_Index]]"` และท้ายไฟล์ `up:: [[Projects/sanook-cli/_Index]]`
+- หลังเขียน: เชื่อม link ไป session/source/code path ที่เกี่ยวข้อง และอัปเดต index นี้ถ้าโน้ตควรถูกค้นเจอในอนาคต
+
+> รายละเอียดทุกโฟลเดอร์ + decision rules → [[Vault Structure Map]]
+
+up:: [[Projects/_Index]]

package/second-brain/Projects/sanook-cli/second-brain-feature-roadmap.md

@@ -0,0 +1,156 @@
+---
+tags: [project, sanook-cli, second-brain, roadmap]
+note_type: project-overview
+created: 2026-06-18
+updated: 2026-06-18
+parent: "[[Projects/sanook-cli/_Index]]"
+source::
+  - src/bin.ts
+  - src/brain.ts
+  - src/memory.ts
+  - src/knowledge.ts
+  - src/mcp-server.ts
+  - src/search/indexer.ts
+  - second-brain/SANOOK.md
+related:: [[Research/2026-06-18-hermes-cli-second-brain-expansion-research]]
+---
+
+# Sanook CLI Second-Brain Feature Roadmap
+
+> Implementation roadmap for doing the second-brain work inside Sanook CLI itself. This supersedes Hermes-specific next actions unless the task is explicitly about Hermes compatibility.
+
+## Current Sanook Capabilities
+
+- `sanook brain init [path]` scaffolds the vault, writes `SANOOK.md`, and stores `brainPath`.
+- `wireBrainMcp()` adds a filesystem MCP server for the vault under `~/.sanook/mcp.json`.
+- `buildBrainContext()` injects `Shared/AI-Context-Index.md`, `current-state.md`, and Memory-Inbox candidates into agent context.
+- `remember` writes to Sanook memory store and routes facts into vault Memory-Inbox.
+- Headless sessions append a daily worklog into `Sessions/`.
+- `sanook index` incrementally indexes vault + memory + sessions + skills.
+- `sanook search` gives BM25 plus optional semantic/hybrid search over the unified index.
+- `sanook mcp serve` exposes `sanook_search`, `sanook_recall`, `sanook_remember`, `sanook_index`, and `sanook_stats`.
+
+## Correct Direction
+
+Do not make the next step `HERMES.md`. For Sanook CLI, the better work is:
+
+1. Make Sanook able to inspect and repair its own second-brain.
+2. Make Sanook able to assemble task-focused context from the vault.
+3. Make Sanook able to run lightweight evals against the vault.
+4. Keep the scaffold taxonomy stable until a command proves a new folder is necessary.
+
+## P0 Features
+
+### `sanook brain doctor`
+
+Status: implemented.
+
+Check the vault itself, not just installation:
+
+- `brainPath` configured and exists.
+- Hot files exist: `SANOOK.md`, `Shared/AI-Context-Index.md`, `Vault Structure Map.md`, `Shared/Operating-State/current-state.md`.
+- Every markdown seed has purpose blockquote, `parent`, and `up::` where expected.
+- `Vault Structure Map.md` mentions every `FOLDERS[]` entry.
+- Search index exists and is fresh enough compared with vault mtimes.
+- MCP wiring points to the configured vault.
+
+### `sanook brain context [--task "..."]`
+
+Status: implemented.
+
+Show the exact context Sanook would inject or retrieve:
+
+- Hot context sources and character counts.
+- Optional task query that runs search and prints top vault/session/skill hits.
+- Clear warning when context is stale, too large, or missing expected files.
+
+### `sanook brain eval`
+
+Status: implemented.
+
+Turn `Evals/second-brain-benchmarks.md` into a runnable sanity check:
+
+- Static cases: required files, routing links, memory policy, index presence.
+- Retrieval cases: search for known benchmark phrases and verify expected files appear.
+- Output pass/partial/fail with file evidence.
+
+## P1 Features
+
+### `sanook brain review`
+
+Status: implemented.
+
+Curator-style health review for the vault:
+
+- Stale context packs.
+- Duplicate or contradictory memory candidates.
+- Sessions without index entries.
+- Evals that have not been updated after framework changes.
+- Markdown routing hygiene: purpose blockquote, `parent`, and `up::`.
+
+### `sanook brain pack list|show`
+
+Make `Shared/Context-Packs/` first-class:
+
+- List available packs with descriptions.
+- Show pack sources and expected use cases.
+- Eventually let the agent choose a pack before loading broader context.
+
+### `sanook brain new <type>`
+
+Template-backed note creation:
+
+- `session`, `bug`, `handoff`, `project`, `golden-case`, `checklist`.
+- Reads destination `_Index.md`, fills frontmatter, and prevents wrong-folder drift.
+
+## P2 Features
+
+- `sanook brain export --for claude|gemini|codex|hermes` for adapter files only when explicitly needed.
+- `sanook brain metrics` for counts, stale notes, index freshness, and retrieval coverage.
+- `sanook brain repair` for safe one-line fixes after `doctor` reports them.
+
+## Folder Policy
+
+No new root folder is needed yet.
+
+Add folders only when a Sanook command needs stable output:
+
+- `Evals/Benchmarks/` when `sanook brain eval` wants per-case files.
+- `Acceptance/Golden-Cases/` when golden fixtures multiply.
+- `Reviews/Vault-Health/` when `sanook brain review` starts writing scheduled reports. The current command is read-only, so no new folder is needed yet.
+
+Avoid broad folders:
+
+- No `Resources/`
+- No `Notes/`
+- No root `AI/`
+- No root `Experiments/`
+
+## First Implementation Slice
+
+Completed on 2026-06-18:
+
+1. Added `src/brain-doctor.ts` with pure check functions and CLI wiring.
+2. Added `src/brain-context.ts` so Sanook can inspect the exact prompt context and task retrieval hits.
+3. Added `src/brain-eval.ts` as a runnable benchmark sanity checker over `Evals/second-brain-benchmarks.md`.
+4. Updated shell/REPL help and changelog.
+5. Verified with targeted second-brain tests and typecheck.
+
+## Second Implementation Slice
+
+Completed on 2026-06-18:
+
+1. Added `src/brain-review.ts` for curator-style vault review.
+2. Wired `sanook brain review [--no-hygiene]` into CLI and help.
+3. Updated generated `Shared/Context-Packs/_Index.md` to link bundled context packs.
+4. Verified with review/scaffold/memory tests and typecheck.
+
+## Next Implementation Slice
+
+Best next code slice:
+
+1. Add `sanook brain pack list|show` for `Shared/Context-Packs/`.
+2. Add `sanook brain new <type>` once note creation templates need a CLI surface.
+3. Add `sanook brain repair` for safe one-line fixes after `doctor`/`review` reports them.
+
+up:: [[Projects/sanook-cli/_Index]]

package/second-brain/README.md

@@ -23,7 +23,7 @@
 1. เปิดโฟลเดอร์นี้ใน **Obsidian** (Open folder as vault)
 2. ให้ AI agent อ่าน `Shared/AI-Context-Index.md` ก่อนทำงานเสมอ
 3. ก่อนสร้างหรือย้ายโน้ต ให้เลือกปลายทางจาก `Vault Structure Map.md` แล้วอ่าน `_Index.md` ของโฟลเดอร์นั้นเพื่อทำตาม **AI Routing Contract**
-4. constitution อยู่ที่ `CLAUDE.md` / `GEMINI.md` / `AGENTS.md` — กฎปฏิบัติของ AI
+4. constitution อยู่ที่ `CLAUDE.md` / `GEMINI.md` / `AGENTS.md` / `SANOOK.md` — กฎปฏิบัติของ AI
 
 ## ปรับให้เป็นของคุณ
 

package/second-brain/Research/2026-06-17-ai-second-brain-method-experiment.md

@@ -0,0 +1,108 @@
+---
+tags: [research, second-brain, ai, experiment]
+note_type: research-note
+created: 2026-06-17
+updated: 2026-06-17
+parent: "[[Research/_Index]]"
+source::
+  - "[[Shared/Scripts/ai-second-brain-method-eval.mjs]]"
+  - "https://arxiv.org/abs/2307.03172"
+  - "https://arxiv.org/abs/2310.11511"
+  - "https://arxiv.org/abs/2404.16130"
+---
+
+# AI Second-Brain Method Experiment — 2026-06-17
+
+> คำถามทดลอง: วิธีจัด second-brain แบบไหนทำให้ AI ใช้งาน vault ได้แม่นที่สุด โดยไม่โหลด context เกินจำเป็น?
+
+## Hypothesis
+
+วิธีที่ดีที่สุดไม่ใช่การให้ AI โหลดทั้ง vault หรือจำจาก session log แต่คือ:
+
+**Single Retrieval Path + JIT Task Rules + Explicit Write Routing + Eval/Consolidation Loop**
+
+ชื่อที่ใช้ใน framework: **Scientific Loop Sequence**.
+
+## Method
+
+รันสคริปต์:
+
+```bash
+node second-brain/Shared/Scripts/ai-second-brain-method-eval.mjs second-brain
+```
+
+สคริปต์เทียบ 5 วิธี:
+
+| Method | แนวคิด |
+|---|---|
+| Session-log only | ใช้ session history เป็น memory หลัก |
+| Folder map only | ใช้ `Vault Structure Map.md` และ index ปลายทาง |
+| Single retrieval index | เริ่มจาก `Shared/AI-Context-Index.md` |
+| Index + JIT context policy | single index + context assembly + โหลดเฉพาะไฟล์จำเป็น |
+| Scientific loop sequence | single index + JIT + write protocol + eval + sleep consolidation + coordination |
+
+Scenarios ที่ใช้วัด:
+
+1. เริ่มงานกับ AI โดยไม่หลุด source of truth
+2. สร้าง/แก้ durable note ให้ถูกที่และค้นเจอภายหลัง
+3. บันทึก preference/decision/fact โดยไม่ append ซ้ำ
+4. นำข้อมูลภายนอกเข้า vault แบบปลอด prompt injection
+5. ทำ sleep-time consolidation และปิด loop ความจำ
+6. กันหลาย agent ชนกันและส่งต่องานได้
+7. งานเทคนิคที่ต้อง verify ก่อนสรุป
+
+Metric:
+
+- **File coverage**: context มีไฟล์ที่ scenario ต้องใช้ไหม
+- **Capability coverage**: วิธีนั้นมี retrieval/routing/eval/memory/coordination ครบไหม
+- **Token economy**: context เฉลี่ยยังใกล้ budget หรือไม่
+
+## Results
+
+| Rank | Method | Score | File Coverage | Capability Coverage | Avg Tokens |
+|---:|---|---:|---:|---:|---:|
+| 1 | Scientific loop sequence | 97.0 | 100% | 100% | ~2890 |
+| 2 | Index + JIT context policy | 62.6 | 64% | 43% | ~2235 |
+| 3 | Single retrieval index | 40.6 | 39% | 18% | ~1932 |
+| 4 | Folder map + destination indexes | 20.8 | 13% | 18% | ~2598 |
+| 5 | Session-log only | 16.4 | 6% | 10% | ~313 |
+
+## Interpretation
+
+**Winner: Scientific Loop Sequence.**
+
+เหตุผล:
+
+- ครอบคลุมงาน AI กับ second-brain ได้ครบทุก scenario
+- ลด hallucination เพราะเริ่มจาก single source of truth แล้วค่อย expand context
+- ลด memory rot เพราะ write operation ต้องเลือก ADD/UPDATE/DELETE/NOOP
+- ลด context rot เพราะใช้ `context-assembly-policy` ก่อนโหลด task rules
+- มี feedback loop จริงผ่าน `eval-loop` และ `sleep-time-consolidation`
+
+ข้อควรระวัง:
+
+- Avg tokens ~2890 สูงกว่า target ~2k
+- บาง scenario สูงเพราะต้องโหลดไฟล์ใหญ่ เช่น `Vault Structure Map.md` และ ingest rules
+- ดังนั้น implementation ต้องใช้แบบ **JIT**: โหลด heading/index ก่อน, expand body เฉพาะเมื่อจำเป็น, และอย่า preload ทุก rule ทุกครั้ง
+
+## Literature Anchor
+
+- Lost in the Middle สนับสนุนว่า context ยาวและตำแหน่งกลางทำให้ retrieval/usefulness ลดลง จึงควรวาง load-bearing context ไว้หัว/ท้าย
+- Self-RAG สนับสนุน retrieve-then-critique/evaluate loop แทนการตอบจาก memory ล้วน
+- GraphRAG สนับสนุนการจัดความรู้เป็น graph/index แทนการกองเอกสารแบบ flat
+
+## Decision
+
+ใช้ **Scientific Loop Sequence** เป็น default AI operating sequence ของ vault:
+
+1. Frame objective/DoD
+2. Retrieve hot context via `Shared/AI-Context-Index.md`
+3. Select AI role for the current phase
+4. Load task-specific rules JIT
+5. Act and verify
+6. Write memory with explicit operation
+7. Eval if non-trivial
+8. Consolidate later via sleep-time loop
+
+related:: [[Runbooks/ai-second-brain-operating-sequence]]
+up:: [[Research/_Index]]

package/second-brain/Research/2026-06-18-ai-token-reduction-frameworks.md

@@ -0,0 +1,55 @@
+---
+tags: [research, token-reduction, ai-agent, sanook-cli]
+note_type: research
+created: 2026-06-18
+updated: 2026-06-18
+parent: "[[Research/_Index]]"
+source:
+  - https://github.com/microsoft/LLMLingua
+  - https://github.com/liyucheng09/Selective_Context
+  - https://github.com/chopratejas/headroom
+---
+
+# AI Token Reduction Frameworks for Sanook CLI
+
+> Research note for choosing a token-reduction framework/pattern to integrate into Sanook CLI.
+
+## Candidates
+
+- Microsoft LLMLingua: strong prompt-compression family, but Python/model-heavy for a Node CLI default.
+- Selective Context: removes low-information lexical units; good fit for a zero-LLM local compressor.
+- Headroom: TypeScript package with Vercel AI SDK adapter, but direct compression requires a running proxy or cloud API key.
+
+## Decision
+
+Use a Sanook-native zero-dependency selective context compressor as the default, and expose Headroom as an optional framework mode.
+
+Rationale:
+
+- Works by default without a Python runtime, model download, proxy, or extra API key.
+- Fits the current Sanook architecture because the biggest waste is stale tool output in multi-step agent loops.
+- Keeps recent tool results full, preserving local correctness while reducing old transcript bloat.
+- Lets users opt into the actual `headroom-ai` Vercel AI SDK adapter when they have a Headroom proxy/cloud compression layer.
+
+## Implementation Shape
+
+- New `contextCompression` config: `selective` (default), `headroom`, or `off`.
+- `SANOOK_CONTEXT_COMPRESSION=off` disables it.
+- `SANOOK_CONTEXT_COMPRESSION=headroom` wraps the Vercel AI SDK model with `headroom-ai/vercel-ai`.
+- `SANOOK_HEADROOM_BASE_URL` and `SANOOK_HEADROOM_API_KEY` can point Sanook at the user's Headroom setup.
+- `selectiveCompressText()` keeps head/tail anchors and high-information lines:
+  - current user-query matches
+  - errors, warnings, failures, tracebacks
+  - file paths and line numbers
+  - diffs and code structure
+  - headings / JSON-like structure
+  - rare lexical terms
+- `selectivelyCompressStaleToolResults()` applies it only to old large tool outputs before each model step.
+- Older stale tool outputs get tighter budgets; the newest tail remains full.
+
+## Verification
+
+- Unit tests cover preservation of query matches, errors, code/diff structure, unchanged short text, stale-tool compression, recency budgets, and recent-tail preservation.
+- Full validation still needs `typecheck`, full test suite, and build after implementation.
+
+up:: [[Research/_Index]]

package/second-brain/Research/2026-06-18-hermes-cli-second-brain-expansion-research.md

@@ -0,0 +1,160 @@
+---
+tags: [research, second-brain, hermes, ai-agent, context-engineering]
+note_type: research-note
+created: 2026-06-18
+updated: 2026-06-18
+parent: "[[Research/_Index]]"
+source::
+  - https://github.com/NousResearch/hermes-agent
+  - https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files
+  - https://hermes-agent.nousresearch.com/docs/user-guide/features/memory
+  - https://hermes-agent.nousresearch.com/docs/user-guide/features/skills
+  - https://hermes-agent.nousresearch.com/docs/user-guide/features/curator
+  - https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
+  - https://docs.langchain.com/oss/python/concepts/memory
+  - https://arxiv.org/abs/2304.03442
+  - https://arxiv.org/abs/2310.08560
+  - https://arxiv.org/abs/2303.11366
+  - https://arxiv.org/abs/2210.03629
+  - https://fortelabs.com/blog/para/
+related:: [[Runbooks/ai-second-brain-operating-sequence]]
+related:: [[Shared/AI-Context-Index]]
+related:: [[Evals/second-brain-benchmarks]]
+---
+
+# Hermes CLI Second-Brain Expansion Research
+
+> Research note for deciding what to add to this second-brain so Hermes CLI can use it better. Created after comparing the current vault structure with Hermes Agent docs, agent memory research, context-engineering guidance, eval patterns, and PARA-style knowledge management. This note becomes stale when Hermes context/memory/skills semantics change materially.
+
+## Bottom Line
+
+Scope correction on 2026-06-18: this note is reference material for Hermes compatibility only. If the objective is Sanook CLI itself, use [[Projects/sanook-cli/second-brain-feature-roadmap]] instead.
+
+อย่าเพิ่ม root-level folder เยอะตอนนี้. โครงสร้างปัจจุบันมี knowledge pipeline, memory, context packs, evals, coordination, and runbooks ครบกว่าค่าเฉลี่ยแล้ว.
+
+สิ่งที่ควรเพิ่มถัดไปคือชั้นที่ทำให้ Hermes ใช้ของที่มีอยู่ได้แม่นขึ้น:
+
+1. `HERMES.md` หรือ `.hermes.md` adapter สำหรับ Hermes CLI โดยเฉพาะ.
+2. `Shared/Hermes/` หรืออย่างน้อย `Shared/Agent-Adapters/hermes.md` สำหรับ config, memory sync, toolset, and curator policy.
+3. `Evals/Benchmarks/` สำหรับ benchmark cases แยกเป็นไฟล์เล็กๆ แทนการโตในไฟล์เดียว.
+4. `Acceptance/Golden-Cases/` สำหรับ input -> expected output ของ Hermes workflows.
+5. `Reviews/Vault-Health/` สำหรับ scheduled curator-style review ของ vault/context/skills.
+
+## Evidence From Hermes
+
+Hermes context files:
+
+- Hermes supports `.hermes.md` / `HERMES.md`, `AGENTS.md`, `CLAUDE.md`, `SOUL.md`, `.cursorrules`, and Cursor rule modules.
+- Priority is first-match: `.hermes.md` -> `AGENTS.md` -> `CLAUDE.md` -> `.cursorrules`; `SOUL.md` is separate global identity.
+- Hermes loads one project context type per session, then progressively discovers subdirectory context files as tools touch paths.
+- Context files are security scanned, truncated, and should stay concise with headers, examples, negative constraints, key paths, and stale-context hygiene.
+
+Implication for this vault:
+
+- Current `AGENTS.md` works as fallback, but Hermes-only usage should prefer a dedicated `HERMES.md` / `.hermes.md` so Hermes does not inherit adapter compromises meant for other agents.
+- Because Hermes progressively discovers subdirectory files, scoped context files can be more useful than one giant root instruction file.
+
+Hermes memory:
+
+- Built-in memory is deliberately tiny: `MEMORY.md` for agent notes and `USER.md` for user profile, both loaded once as a frozen snapshot at session start.
+- Hermes explicitly separates always-on memory from on-demand session search.
+- Memory writes can be gated with approval, and memory entries should be compact, specific, and non-duplicative.
+
+Implication for this vault:
+
+- Keep Hermes memory small and use the vault as the long-term source of truth.
+- Add a Hermes memory sync policy: what goes to `~/.hermes/memories/MEMORY.md`, what stays in `Shared/User-Memory`, what is retrieved on demand from vault search/session logs.
+
+Hermes skills:
+
+- Skills are on-demand knowledge documents with progressive disclosure.
+- `SKILL.md` supports references, templates, scripts, assets, platform restrictions, required environment variables, and verification sections.
+- Hermes can scan external skill directories, but writable external dirs are not a write-protection boundary.
+
+Implication for this vault:
+
+- Current `.agents/skills/` can become a shared skill source, but it needs an explicit policy for which skills are read-only, owner-authored, or agent-created.
+- Useful repeatable vault workflows should graduate into Hermes skills only after they have examples, pitfalls, and verification.
+
+Hermes curator:
+
+- The curator tracks skill usage, marks stale skills, archives long-unused skills, and can optionally run an LLM consolidation pass.
+- It has status, dry-run, backup, rollback, pin, and archive commands.
+
+Implication for this vault:
+
+- Add curator-like vault health reviews: stale context, duplicated rules, unused context packs, benchmark drift, and skills that should be archived or pinned.
+
+## Evidence From Agent Research
+
+Context engineering:
+
+- Anthropic frames context as finite and context engineering as the task of curating all tokens available to an agent across long-running loops, not just writing better prompts.
+- This supports the current Scientific Loop Sequence and argues for smaller, task-specific retrieval bundles rather than a larger global instruction file.
+
+Memory taxonomy:
+
+- LangGraph separates short-term thread-scoped memory from long-term memory across conversations, and uses semantic, episodic, and procedural memory categories.
+- Generative Agents stores experiences, synthesizes reflections, and retrieves memories dynamically for planning.
+- MemGPT argues for tiered memory and movement between fast context and slower external memory.
+- Reflexion stores reflective text in episodic memory after feedback to improve future trials.
+- ReAct shows the value of interleaving reasoning/action with external information retrieval.
+
+Implication for this vault:
+
+- Current folders already map well:
+  - semantic memory -> `Learning/`, `Distillations/`, `Entities/`, `Shared/Core-Facts/`
+  - episodic memory -> `Sessions/`, `Retrospectives/`, `Traces/`
+  - procedural memory -> `Runbooks/`, `Playbooks/`, `Skills/`, `.agents/skills/`
+  - eval/reflection memory -> `Evals/`, `Acceptance/`, `Reviews/`
+- The missing piece is not another generic "Resources" folder. It is sharper eval cases, Hermes adapter policy, and scheduled consolidation.
+
+PKM / PARA:
+
+- PARA's Projects / Areas / Resources / Archives split supports action-oriented retrieval.
+- This vault already extends PARA with AI-specific layers: Evals, Acceptance, Rules, Context-Packs, Provenance, Coordination.
+
+Implication for this vault:
+
+- Avoid adding broad folders like `Resources/`, `Notes/`, or `AI/`; they would overlap existing canonical homes.
+
+## Gap Analysis
+
+| Gap | Current coverage | Recommended addition | Priority |
+|---|---|---|---|
+| Hermes-specific project context | `AGENTS.md` only | `HERMES.md` or `.hermes.md` pointing to hot path and Hermes-only rules | P0 |
+| Hermes memory policy | `Shared/User-Memory`, `Shared/Memory-Inbox`, `USER.md` | `Shared/Hermes/memory-sync-policy.md` or `Shared/Agent-Adapters/hermes-memory.md` | P0 |
+| Hermes skill lifecycle | `.agents/skills`, `Skills/`, `Shared/Rules/skills-admission` | `Shared/Hermes/skill-lifecycle.md` plus first Hermes skill for second-brain maintenance | P1 |
+| Atomic benchmarks | `Evals/second-brain-benchmarks.md` | `Evals/Benchmarks/<case-id>.md` | P1 |
+| Golden fixtures | `Acceptance/golden-case-template.md` | `Acceptance/Golden-Cases/<workflow>.md` | P1 |
+| Scheduled vault health | `Reviews/`, `Runbooks/sleep-time-consolidation.md` | `Reviews/Vault-Health/YYYY-MM-DD.md` | P1 |
+| Prompt-injection trust boundary | `Intake/_Quarantine`, `ingest-quarantine`, Hermes scanner | `Shared/Security/trust-boundaries.md` only if rules grow beyond current files | P2 |
+| Tool inventory and MCP capabilities | `Tools/`, `Shared/mcp-servers`, `Tech-Standards` | `Shared/Hermes/toolsets.md` if Hermes profiles/toolsets become important | P2 |
+| Output artifacts per project | `Projects/<proj>/` role allows deliverables | Add `Projects/<proj>/Artifacts/` only inside active projects with many generated files | P2 |
+
+## Recommended Next Build
+
+Best next bundle:
+
+1. Add `second-brain/HERMES.md`.
+2. Add `second-brain/Shared/Hermes/_Index.md`.
+3. Add `second-brain/Shared/Hermes/memory-sync-policy.md`.
+4. Add `second-brain/Shared/Hermes/skill-lifecycle.md`.
+5. Add `second-brain/Shared/Context-Packs/hermes-cli-vault-maintenance.md`.
+6. Split 3-5 high-value cases from `Evals/second-brain-benchmarks.md` into `Evals/Benchmarks/`.
+
+Implementation caution:
+
+- If adding new folders, update [[Vault Structure Map]] and any folder scaffold source such as `src/brain.ts`.
+- If adding only files under existing folders, keep the current taxonomy stable.
+- Do not mirror Hermes `~/.hermes/` wholesale into the vault; keep local runtime state in Hermes home and store only policy, reviewed snapshots, and durable decisions here.
+
+## Do Not Add Yet
+
+- `Resources/` root folder: overlaps `Research/`, `Learning/`, and `Distillations/`.
+- `Notes/` root folder: becomes a junk drawer and weakens routing.
+- `AI/` root folder: duplicates `Shared/AI-Context-Index`, agent adapters, rules, and context packs.
+- `Archive/` root folder: `Shared/Archive/` already exists.
+- `Experiments/` root folder: use `Research/`, `Evals/`, or `Sessions/` depending on artifact type.
+
+up:: [[Research/_Index]]