hypomnema 1.0.0

package/templates/Overview.md

@@ -0,0 +1,50 @@
+---
+title: Wiki Overview
+type: reference
+updated: YYYY-MM-DD
+tags: [wiki, overview]
+---
+
+# Wiki Overview
+
+> A high-level map of this knowledge base. For the full page catalog see [[index]].
+
+---
+
+## Knowledge Areas
+
+<!-- Group your pages by domain/topic area -->
+<!-- Add sections as your wiki grows -->
+
+### Concepts
+
+<!-- [[concepts/topic]] — brief description -->
+
+### Playbooks
+
+<!-- [[playbooks/topic]] — how to do X -->
+
+### Learnings
+
+<!-- [[learnings/topic]] — what was learned and when -->
+
+### Tool Evaluations
+
+<!-- [[tool-evaluations/tool-name]] — adopt / hold / reject -->
+
+---
+
+## Projects
+
+<!-- Links to active and archived project indexes -->
+
+| Project | Status | Last Session |
+|---------|--------|-------------|
+| <!-- [[projects/name/index\|name]] --> | active | YYYY-MM-DD |
+
+---
+
+## Sources
+
+<!-- Key external sources ingested into this wiki -->
+<!-- [[sources/slug]] — title (YYYY-MM-DD) -->

package/templates/SCHEMA.md

@@ -0,0 +1,106 @@
+---
+title: Wiki Schema
+type: schema
+updated: YYYY-MM-DD
+version: 1.0
+---
+
+# Wiki Schema
+
+The type system and vocabulary standard for this wiki.
+Read this before any wiki operation (ingest / query / lint).
+
+---
+
+## 1. Page Type Taxonomy
+
+| type | location | description | mutability |
+|------|----------|-------------|------------|
+| `concept` | `pages/` | Principles, theories, design ideas | mutable |
+| `source-summary` | `pages/` | Summary of a `sources/` raw document | semi-immutable |
+| `entity` | `pages/people/`, `pages/orgs/` | People, organizations | mutable |
+| `tool-eval` | `pages/tool-evaluations/` | Tool evaluations (adopt / reject) | mutable |
+| `prompt-pattern` | `pages/prompt-patterns/` | Verified prompt patterns | mutable |
+| `playbook` | `pages/playbooks/` | Repeatable how-to procedures | mutable |
+| `learning` | `pages/learnings/` | Discoveries, gotchas, lessons learned | append-only |
+| `tip` | `pages/tips/` | Practical environment/tool tips | mutable |
+| `feedback` | `pages/feedback/` | AI behavior correction records | append-only |
+| `reference` | `pages/` | Config snapshots, external system references | mutable |
+| `synthesis` | `pages/syntheses/` | Cross-page synthesis (3+ pages analyzed) | mutable |
+| `weekly-journal` | `journal/weekly/YYYY-Www.md` | Weekly session/ingest summary | append-only |
+| `prd` | `projects/*/prd.md` | Project purpose, success criteria, constraints | mutable |
+| `adr` | `projects/*/decisions/NNNN-*.md` | Architecture decision records | immutable |
+| `session-log` | `projects/*/session-log/YYYY-MM.md` | Chronological session narrative (monthly) | append-only |
+| `session-state` | `projects/*/session-state.md` | Next-session handoff — overwritten each close | overwrite |
+| `project-index` | `projects/*/index.md` | Project overview + progress checklist | mutable |
+| `open-questions` | `pages/open-questions.md` | Unresolved question queue | append+resolve |
+| `schema` | `SCHEMA.md` (this file) | Type system + vocabulary standard | versioned |
+| `log` | `log.md` | Append-only activity log (ingest, session, note entries) | append-only |
+| `config` | `hypo-config.md` | Wiki root marker + user settings | mutable |
+
+**Notes**:
+- `append-only`: never delete/modify existing entries. Corrections go as new entries (`[supersedes: YYYY-MM-DD]`).
+- `immutable`: deprecated/superseded markers allowed, content edits forbidden.
+- `semi-immutable`: factual corrections OK; interpretation/synthesis goes in `pages/` as a new page.
+
+---
+
+## 2. Memory Layer Files
+
+Files responsible for session continuity — separate from the type taxonomy above.
+
+| file | role | constraint |
+|------|------|-----------|
+| `hot.md` (root) | Active project pointer table + last session date | Pointers only. No session content. |
+| `projects/<name>/hot.md` | Last session snapshot — "what was done" | 500-word cap. No next-tasks. Overwrite each close. |
+| `projects/<name>/session-state.md` | Next-session handoff — "what to do next" | Overwrite each close. Read at session start. |
+| `projects/<name>/session-log/YYYY-MM.md` | Append-only narrative timeline (monthly) | No edits to existing entries. |
+| `pages/open-questions.md` | Cross-project unresolved question queue | Append + mark resolved. |
+
+**Operations**:
+- Session start: root `hot.md` → project `hot.md` → `session-state.md`
+- Session close: update project `hot.md` (what was done) + `session-state.md` (what to do next) + root `hot.md`
+
+---
+
+## 3. Required Frontmatter Fields
+
+```yaml
+---
+title: <human-readable title>
+type: <type from taxonomy above>
+updated: YYYY-MM-DD
+tags: [tag1, tag2]
+---
+```
+
+Optional fields (add as needed):
+
+```yaml
+confidence: high | medium | low | speculative
+evidence_strength: direct | inferred | hearsay
+scope: always | project | session
+source: <slug or URL>
+verify_by: <question to re-check at next review>
+verify_by_date: YYYY-MM-DD
+```
+
+---
+
+## 4. Tag Vocabulary
+
+Use lowercase, hyphenated tags. Keep the vocabulary small and consistent.
+
+**Domain tags**: `ai`, `dev`, `ops`, `security`, `data`, `design`, `management`
+**Status tags**: `draft`, `stable`, `deprecated`, `needs-review`
+**Meta tags**: `wiki`, `index`, `operations`, `guide`, `schema`
+
+---
+
+## 5. Source-First Principle
+
+Wiki compound value comes from **external source ingestion**, not self-reference.
+
+- At least 1 new external source per week in `sources/`
+- `source: session:*` only chains → drift risk (see `pages/learnings/`)
+- Every `source-summary` must reference a file in `sources/`

package/templates/hot.md

@@ -0,0 +1,22 @@
+---
+title: Hot Cache — Pointer
+type: reference
+updated: YYYY-MM-DD
+tags: [wiki, operations]
+---
+
+# Hot Cache
+
+> Read at session start → navigate to the relevant project session-state.md and hot.md.
+> Update at session close: project session-state.md, project hot.md, and this file's "Active Projects" table.
+
+## Active Projects
+
+| Project | Last Session | Hot Cache |
+|---|---|---|
+
+## Session Start Checklist
+
+1. Check this file for the relevant project link
+2. Read `projects/<name>/session-state.md` for next tasks if it exists
+3. Read `projects/<name>/hot.md` for project background

package/templates/hypo-automation.md

@@ -0,0 +1,69 @@
+---
+title: Wiki Automation
+type: reference
+updated: YYYY-MM-DD
+tags: [wiki, automation, hooks]
+---
+
+# Wiki Automation
+
+How Hypomnema's Claude Code hooks work together to automate context injection,
+session continuity, and git sync.
+
+---
+
+## Hook Overview
+
+| Hook | Event | Purpose |
+|------|-------|---------|
+| `hypo-session-start.mjs` | Session start | Injects `hot.md` and `session-state.md` into context |
+| `hypo-first-prompt.mjs` | First user prompt | Injects active project context on first message |
+| `hypo-auto-stage.mjs` | File save | Auto-stages changed wiki files |
+| `hypo-auto-commit.mjs` | Session stop | Commits and pushes staged wiki changes |
+| `hypo-compact-guard.mjs` | Pre-compact | Blocks `/compact` if session-log entry is missing |
+| `hypo-hot-rebuild.mjs` | Post-tool | Rebuilds `hot.md` from project hot caches |
+| `hypo-personal-check.mjs` | Pre-tool | Validates config and blocks on lint errors |
+
+All hooks run **locally** — no network requests.
+
+---
+
+## Session Flow
+
+```
+Session start
+  └─ hypo-session-start.mjs → reads hot.md + session-state.md → injects context
+
+During session
+  └─ hypo-auto-stage.mjs → auto-stages .md edits in wiki dir
+  └─ hypo-hot-rebuild.mjs → refreshes hot.md after project hot.md changes
+
+Session end
+  └─ /session-compact → writes session-log, session-state, ADRs
+  └─ hypo-auto-commit.mjs → git commit + push
+```
+
+---
+
+## `.hypoignore`
+
+Files matching patterns in `.hypoignore` are excluded from hook reads and index lookups.
+They remain on disk but are invisible to all Hypomnema tooling.
+
+```
+# Example .hypoignore
+journal/
+*private*
+sources/*.pdf
+```
+
+Edit `.hypoignore` in your wiki root to exclude additional files or directories from hook context.
+
+---
+
+## Lint Gate
+
+`hypo-personal-check.mjs` runs `lint.mjs` before destructive operations.
+If **blocker** errors are found, the operation is blocked until errors are resolved.
+
+Run `/hypo:lint` to check and fix issues.

package/templates/hypo-config.md

@@ -0,0 +1,41 @@
+---
+title: Hypomnema Config
+type: config
+version: "1.0.0"
+created: YYYY-MM-DD
+---
+
+# Hypomnema Config
+
+This file marks the root of your Hypomnema wiki.
+Hooks use it to locate the wiki root automatically — do not delete or move it.
+
+## Settings
+
+To override the wiki root path, set the `HYPO_DIR` environment variable
+instead of editing this file.
+
+To bypass the session-close gate (e.g. for trivial sessions):
+```
+HYPO_SKIP_GATE=1
+```
+
+## Layout
+
+```
+<hypo-root>/
+├── hypo-config.md      ← you are here (root marker)
+├── index.md            ← searchable page index
+├── hot.md              ← active-project pointer table
+├── log.md              ← chronological activity log
+├── hypo-guide.md       ← operations guide
+├── SCHEMA.md           ← type system reference
+├── .hypoignore         ← glob patterns excluded from hooks
+├── pages/              ← permanent knowledge pages
+├── projects/           ← project work artifacts
+│   └── <name>/
+│       ├── index.md    ← project overview (working_dir: field)
+│       ├── hot.md      ← project-scoped session snapshot
+│       └── session-log/    ← monthly logs (YYYY-MM.md)
+└── sources/            ← raw ingested sources (read-only)
+```

package/templates/hypo-guide.md

@@ -0,0 +1,146 @@
+---
+title: Wiki Operations Guide
+type: reference
+updated: YYYY-MM-DD
+tags: [wiki, guide, operations]
+---
+
+# Wiki Operations Guide
+
+How to run this wiki. For the type system, see [[SCHEMA]].
+
+> **Before any wiki task**: read `SCHEMA.md` → `hypo-guide.md` on the first wiki operation of a session. Reuse for subsequent operations. Re-read after `/compact`, context resume, or if unsure.
+
+---
+
+## 1. Why This Wiki Exists
+
+Standard RAG chunks sources as-is — contradictions, stale content and all.
+This wiki is different: **an LLM reads each source, synthesizes it, and updates existing pages**.
+Over time, new sources *update* pages more than they *create* them — that's when compound value starts.
+
+---
+
+## 2. Directory Layout
+
+```
+<hypo-root>/
+├── hypo-config.md      ← root marker (do not delete)
+├── index.md            ← searchable page catalog
+├── hot.md              ← active-project pointer table
+├── log.md              ← append-only activity log
+├── SCHEMA.md           ← type system reference
+├── hypo-guide.md       ← this file
+├── .hypoignore         ← privacy/exclusion patterns
+├── pages/              ← permanent knowledge pages (subdirs added on demand)
+│   ├── learnings/      (optional)
+│   ├── playbooks/      (optional)
+│   ├── feedback/       (optional)
+│   └── open-questions.md  (optional)
+├── projects/           ← project work artifacts
+│   └── <name>/
+│       ├── index.md          ← overview (working_dir: field)
+│       ├── prd.md            ← purpose / success criteria
+│       ├── hot.md            ← session snapshot
+│       ├── session-state.md  ← next-session handoff
+│       ├── session-log/      ← monthly narrative logs
+│       └── decisions/        ← ADRs (0001-*.md …)
+└── sources/            ← raw ingested sources (never edit)
+```
+
+**Rule**: never edit `sources/`. All knowledge creation goes in `pages/` and `projects/`.
+
+---
+
+## 3. Core Operations
+
+### Session Start
+
+1. Read root `hot.md` → identify active project
+2. If `cwd` matches `projects/<name>/index.md`'s `working_dir:` field → read `projects/<name>/session-state.md` first
+3. Read `projects/<name>/hot.md` for background context
+4. Offer: "Continuing [X] from last session — shall we pick up?"
+
+### Session Close
+
+Trigger: explicit close mention, `/compact` request, or context limit approaching.
+
+1. Update `projects/<name>/session-state.md` (next tasks, overwrite)
+2. Update `projects/<name>/hot.md` (what was done, ≤500 words, overwrite)
+3. Append to `projects/<name>/session-log/YYYY-MM.md` (narrative entry, append-only)
+4. Update root `hot.md` pointer table + date
+
+Skip session close for: single bug fix, single-file edit, Q&A only.
+
+### Ingest (external source → wiki)
+
+1. Save raw source to `sources/<slug>.<ext>` (never edit after)
+2. Read and synthesize
+3. Update or create pages in `pages/` with frontmatter `source: <slug>`
+4. Append to `index.md`
+5. Append to `log.md`
+
+### Query
+
+1. Read `index.md` first
+2. Cross-reference related pages
+3. Synthesize answer — cite `[[page-slug]]` links
+
+---
+
+## 4. Page Creation Checklist
+
+- [ ] Correct `type` from SCHEMA taxonomy
+- [ ] `updated: YYYY-MM-DD` (today's date)
+- [ ] Meaningful `tags` (see SCHEMA §4)
+- [ ] Added to `index.md`
+- [ ] Cross-links to related pages
+
+---
+
+## 5. Project Lifecycle
+
+### Start a project
+
+```
+projects/<name>/
+├── index.md          (working_dir: /path/to/repo)
+├── prd.md
+└── session-state.md
+```
+
+Add to root `hot.md` active projects table.
+
+### Close a project
+
+1. Write final `session-state.md` (mark as complete)
+2. Update `projects/<name>/index.md` status
+3. Remove from root `hot.md` active table (or mark archived)
+
+---
+
+## 6. ADR Format
+
+```
+projects/<name>/decisions/NNNN-short-title.md
+```
+
+```yaml
+---
+title: "NNNN: Short Title"
+type: adr
+status: accepted | deprecated | superseded
+date: YYYY-MM-DD
+superseded_by: NNNN   # if applicable
+---
+```
+
+ADRs are immutable once accepted. Mark deprecated/superseded but never edit content.
+
+---
+
+## 7. Maintenance
+
+- **Weekly**: check `pages/open-questions.md` for resolved items
+- **Monthly**: review `log.md` for source-starved weeks (< 1 external source)
+- **On schema change**: bump `SCHEMA.md` version, update this guide if layout changed

package/templates/hypo-help.md

@@ -0,0 +1,53 @@
+---
+title: Hypomnema — Command Reference
+type: reference
+updated: YYYY-MM-DD
+tags: [hypo, commands, reference]
+---
+
+# Hypomnema Command Reference
+
+Quick reference for all `/hypo:*` commands.
+
+---
+
+## Setup & Maintenance
+
+| Command | Description |
+|---------|-------------|
+| `/hypo:init` | Initialize a new wiki (first-time setup) |
+| `/hypo:doctor` | Health check — verifies dirs, hooks, settings |
+| `/hypo:upgrade` | Update hooks and settings to latest version |
+| `/hypo:uninstall` | Remove hooks and deregister from settings.json |
+
+---
+
+## Daily Operations
+
+| Command | Description |
+|---------|-------------|
+| `/hypo:resume` | Show next tasks from session-state.md |
+| `/hypo:query <terms>` | Full-text search + synthesis across all pages |
+| `/hypo:ingest <url/text>` | Add external knowledge to sources/ and synthesize |
+| `/hypo:feedback <topic>` | Record AI behavior correction for a topic |
+| `/hypo:stats` | Wiki health summary — page counts, ADRs, last activity |
+
+---
+
+## Knowledge Curation
+
+| Command | Description |
+|---------|-------------|
+| `/hypo:crystallize` | Find synthesis candidates — tag clusters, unlinked pages, drafts |
+| `/hypo:verify` | Review overdue verify_by deadlines |
+| `/hypo:lint` | Validate frontmatter and `[[wikilinks]]` |
+| `/hypo:graph` | Generate link graph (json / mermaid / dot) |
+
+---
+
+## Tips
+
+- **Session start**: `hot.md` → `session-state.md` → begin work
+- **Session end**: run `/session-compact` (if available) or update session-state.md manually
+- **Privacy**: edit `.hypoignore` to exclude sensitive paths from hooks
+- **Verify schedule**: add `verify_by:` and `verify_by_date:` to pages you want to review periodically

package/templates/index.md

@@ -0,0 +1,44 @@
+---
+title: Wiki Index
+type: reference
+updated: YYYY-MM-DD
+tags: [wiki, index]
+---
+
+# Wiki
+
+> Master index of all knowledge pages.
+> Format: `[[slug]] — one-line description`
+> Keep entries alphabetical within each section.
+
+---
+
+## Projects
+
+<!-- Add project entries here as you create them -->
+<!-- [[projects/my-project/index|my-project]] — brief description -->
+
+---
+
+## Pages
+
+<!-- Knowledge pages, indexed by slug -->
+
+### Learnings
+
+<!-- [[learnings/topic]] — what was learned -->
+
+### Playbooks
+
+<!-- [[playbooks/topic]] — how to do X -->
+
+### Tool Evaluations
+
+<!-- [[tool-evaluations/tool-name]] — evaluation notes -->
+
+---
+
+## Sources
+
+<!-- Ingested external sources -->
+<!-- [[sources/slug]] — source title (YYYY-MM-DD) -->

package/templates/log.md

@@ -0,0 +1,25 @@
+---
+title: Activity Log
+type: log
+updated: YYYY-MM-DD
+---
+
+# Activity Log
+
+> Chronological record of all substantial wiki operations.
+> Append a new `##` entry at session close.
+
+## Entry types
+
+- `session` — non-trivial multi-file work session
+- `ingest`  — new external source added to sources/
+- `note`    — standalone note (not a full session)
+
+## Format
+
+```
+## [YYYY-MM-DD] session | <project-name>
+## [YYYY-MM-DD] ingest | <source-title>
+```
+
+---

package/templates/pages/_index.md

@@ -0,0 +1,61 @@
+---
+title: Pages Index
+type: reference
+updated: YYYY-MM-DD
+tags: [wiki, index, pages]
+---
+
+# Pages
+
+> All permanent knowledge pages, grouped by type.
+> Format: `[[slug]] — one-line description`
+> Keep entries alphabetical within each section.
+
+---
+
+## Concepts
+
+<!-- Principles, theories, design ideas -->
+<!-- [[concepts/topic]] — description -->
+
+---
+
+## Learnings
+
+<!-- Discoveries, gotchas, lessons learned (append-only) -->
+<!-- [[learnings/topic]] — description -->
+
+---
+
+## Playbooks
+
+<!-- Repeatable how-to procedures -->
+<!-- [[playbooks/topic]] — how to do X -->
+
+---
+
+## Tool Evaluations
+
+<!-- Tool adopt / hold / reject records -->
+<!-- [[tool-evaluations/tool-name]] — evaluation summary -->
+
+---
+
+## Prompt Patterns
+
+<!-- Verified prompt patterns for LLM interactions -->
+<!-- [[prompt-patterns/pattern-name]] — description -->
+
+---
+
+## Syntheses
+
+<!-- Cross-page synthesis (3+ pages analyzed) -->
+<!-- [[syntheses/topic]] — synthesis summary -->
+
+---
+
+## Feedback
+
+<!-- AI behavior correction records -->
+<!-- [[feedback/topic]] — correction description -->

package/templates/projects/_template/hot.md

@@ -0,0 +1,28 @@
+---
+title: <project-name> — Hot Cache
+type: reference
+updated: YYYY-MM-DD
+tags: [hot-cache, project]
+---
+
+# <project-name> — Hot Cache
+
+> Project-scoped session snapshot. Updated at session close.
+> Root `hot.md` holds the pointer table; this file holds the detail.
+
+## Background
+
+(1-3 sentences on what this project is and where it stands.)
+
+## Current Focus
+
+(What's being actively worked on right now.)
+
+## Key Decisions
+
+<!-- Brief pointers to important ADRs or design choices -->
+<!-- [[decisions/0001-topic]] — decision summary -->
+
+## Blockers / Open Questions
+
+<!-- (none) -->

package/templates/projects/_template/index.md

@@ -0,0 +1,39 @@
+---
+title: <project-name> — Index
+type: project-index
+status: active
+started: YYYY-MM-DD
+updated: YYYY-MM-DD
+working_dir: ~/path/to/project
+tags: [project]
+---
+
+# <project-name>
+
+> One-line description of the project.
+
+---
+
+## Progress
+
+- [ ] Phase 1 — Description
+- [ ] Phase 2 — Description
+
+---
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `prd.md` | Purpose and success criteria |
+| `hot.md` | Session snapshot and background |
+| `session-state.md` | Next-session handoff |
+| `session-log/` | Monthly work narrative |
+| `decisions/` | Architecture decision records |
+
+---
+
+## Links
+
+- [[projects/<project-name>/prd|PRD]]
+- [[projects/<project-name>/hot|Hot Cache]]