hypomnema 1.0.0

package/commands/ingest.md

@@ -0,0 +1,85 @@
+---
+description: Ingest an external source into the wiki
+---
+
+You are running `/hypo:ingest`. Save a raw source and synthesize it into wiki pages.
+
+## What this does
+
+- Saves raw source content to `sources/<slug>.<ext>` (never edited after)
+- Synthesizes the source into one or more pages in `pages/`
+- Updates `index.md` with new or updated pages
+- Appends an entry to `log.md`
+
+---
+
+## Step 1 — Collect source details
+
+Ask the user:
+
+1. **Source**: "What is the source? (paste text, provide a file path, or give a URL)"
+2. **Slug**: "What slug should this source have? (e.g. `openai-swarm-paper`, `team-retro-2026-04`)"
+   - Default: derive from title or filename
+
+If a URL is provided, fetch the content. If a file path is provided, read it.
+
+---
+
+## Step 2 — Check for orphaned sources
+
+Locate the Hypomnema package root. Run the ingest helper to surface existing orphaned sources:
+
+```bash
+node <package-root>/scripts/ingest.mjs [--hypo-dir="<path>"]
+```
+
+If there are orphaned sources already in `sources/`, ask: "There are N unprocessed sources — do you want to ingest one of those instead?"
+
+---
+
+## Step 3 — Save raw source
+
+Save the raw content to `sources/<slug>.<ext>` (use `.md` for text, `.txt` for plain text, `.pdf` or original extension for documents).
+
+Do **not** modify or summarize in the sources file — save it as-is.
+
+---
+
+## Step 4 — Synthesize
+
+Read and synthesize the source:
+
+1. **Check index.md** — does a page on this topic already exist?
+   - If yes: update the existing page (merge new information, mark `updated:` today)
+   - If no: create a new page in `pages/` with `type: source-summary` and `source: <slug>`
+
+2. **Frontmatter** for new pages:
+   ```yaml
+   ---
+   title: "<descriptive title>"
+   type: source-summary
+   updated: YYYY-MM-DD
+   tags: [<relevant tags>]
+   source: <slug>
+   confidence: high | medium | low
+   evidence_strength: direct
+   ---
+   ```
+
+3. **Content**: synthesis in your own words — not a copy of the source. Include key insights, quotes as blockquotes, and cross-links to related pages.
+
+---
+
+## Step 5 — Update index.md and log.md
+
+- Append a line to `index.md`: `- [[pages/<slug>]] — <one-line description>`
+- Append to `log.md`: `- YYYY-MM-DD ingest: [[pages/<slug>]] from sources/<slug>.<ext>`
+
+---
+
+## Step 6 — Report
+
+Show:
+- ✓ Saved source: `sources/<slug>.<ext>`
+- ✓ Created/Updated: `pages/<slug>.md`
+- ↪ Updated: `index.md`, `log.md`

package/commands/init.md

@@ -0,0 +1,101 @@
+---
+description: Initialize a new Hypomnema wiki
+---
+
+You are running `/hypo:init`. Set up a new personal wiki powered by Hypomnema.
+
+**If the user passes a remote URL** (e.g. `/hypo:init --from-remote git@github.com:user/wiki.git`), skip the wizard and go directly to [Step 2a — From Remote](#step-2a).
+
+---
+
+## What this does
+
+- Creates the Hypomnema directory structure (`pages/`, `projects/`, `sources/`, etc.)
+- Copies baseline template files (`index.md`, `hot.md`, `log.md`, `hypo-config.md`, `SCHEMA.md`, `hypo-guide.md`)
+- Installs Claude Code hooks for automatic context injection
+- Merges hook entries into `~/.claude/settings.json` (idempotent)
+- Optionally sets up git with a remote
+
+---
+
+## Step 1 — Wizard
+
+Ask the following questions **one at a time**. Use the default if the user presses Enter.
+
+1. **Wiki directory**
+   > "Where should your wiki live? [~/hypomnema]"
+   Default: `~/hypomnema`
+
+2. **Install hooks**
+   > "Install Claude Code hooks for automatic context injection? [yes]"
+   Default: yes
+
+3. **Codex hooks** — ask only if the user answered **yes** to hooks AND `~/.codex/` exists
+   > "Also install Codex-compatible hooks in ~/.codex/hooks/? [yes]"
+   Default: yes
+   Skip this question if hooks=no or `~/.codex/` does not exist.
+
+4. **Git remote** (optional)
+   > "Git remote URL for sync/backup? (Enter to skip)"
+   Default: skip
+
+---
+
+## Step 2a — From Remote (skip wizard) {#step-2a}
+
+If the user provided `--from-remote <url>`, run:
+
+```bash
+node <package-root>/scripts/init.mjs \
+  --from-remote="<url>" \
+  --hypo-dir="<hypo-dir>" \
+  [--no-hooks] \
+  [--codex]
+```
+
+- `--hypo-dir` defaults to `~/hypomnema` if not specified.
+- The script clones the remote, validates that `hypo-config.md` exists, installs hooks, and merges `~/.claude/settings.json`.
+- If the cloned repo is not a Hypomnema wiki (no `hypo-config.md`), the clone is removed and the command exits with an error.
+- Skip to **Step 3** after running.
+
+---
+
+## Step 2 — Run the init script (new wiki)
+
+Locate the Hypomnema package root (the directory containing this file's parent `commands/`).
+Then run:
+
+```bash
+node <package-root>/scripts/init.mjs \
+  --hypo-dir="<hypo-dir>" \
+  [--no-hooks] \
+  [--codex] \
+  [--git-remote=<url>] \
+  [--no-git-init]
+```
+
+Add `--dry-run` first to preview the changes, then run without it.
+
+After init, the user can edit `.hypoignore` directly to exclude any files or directories from hook context.
+
+---
+
+## Step 3 — Report results
+
+Show the script output to the user:
+- ✓ Created files/dirs (includes journal/, projects/_template/, first commit)
+- ⊘ Skipped (already existed — no overwrites)
+- ↪ Merged into settings.json / pushed to remote
+- ✗ Errors (if any)
+
+---
+
+## Step 4 — Next steps
+
+After a successful init, tell the user:
+
+1. **Restart Claude Code** (or reload the window) so the new hooks take effect.
+2. Run `/hypo:doctor` to verify the installation.
+3. Open `<hypo-dir>/hypo-guide.md` to read the operations guide.
+
+If hooks were installed: note that `~/.claude/settings.json` was updated and a restart is required.

package/commands/lint.md

@@ -0,0 +1,55 @@
+---
+description: Validate wiki pages for frontmatter correctness and broken wikilinks
+---
+
+You are running `/hypo:lint`. Validate all wiki pages for frontmatter correctness and broken `[[wikilink]]` references.
+
+## What this checks
+
+- Every `.md` file under `pages/` and `projects/` should have frontmatter (missing frontmatter is a warning)
+- Required fields: `title`, `type`
+- `type` must be one of the recognised values (concept, source-summary, learning, adr, …)
+- `updated` field should be present
+- All `[[wikilinks]]` must resolve to an existing page slug
+
+---
+
+## Step 1 — Locate package root
+
+Locate the Hypomnema package root (the directory containing this file's parent `commands/`).
+
+If the user specified a Hypomnema directory, pass it as `--hypo-dir="<path>"`. Otherwise omit the flag and the script resolves the Hypomnema root automatically via `HYPO_DIR` → `hypo-config.md` scan → `~/hypomnema`.
+
+---
+
+## Step 2 — Run lint
+
+```bash
+node <package-root>/scripts/lint.mjs [--hypo-dir="<path>"] [--json] [--fix]
+```
+
+Options:
+- `--json` — output results as JSON (useful for tooling)
+- `--fix` — auto-add missing `updated` field (safe repairs only; no other fields are modified)
+
+Show the output verbatim.
+
+---
+
+## Step 3 — Interpret results
+
+- `✓ No lint issues found` — Hypomnema is clean
+- `✗ <file>: <message>` — error (missing required field or malformed frontmatter); must be fixed
+- `⚠ <file>: <message>` — warning (unknown type, missing `updated`, broken link); worth fixing
+
+A non-zero exit code means at least one **error** was found (warnings alone do not produce a non-zero exit code).
+
+---
+
+## Step 4 — Offer to fix
+
+For **broken wikilinks**: list the affected files and ask if the user wants help correcting the links now.
+
+For **missing `updated`**: suggest running with `--fix` to auto-add `updated: <today>` to each affected page's frontmatter. Note: `--fix` only repairs files that already have a valid, closed frontmatter block — files with no frontmatter or malformed frontmatter are skipped.
+
+For **missing required fields** (`title`, `type`): open the affected files and help the user fill them in.

package/commands/query.md

@@ -0,0 +1,55 @@
+---
+description: Query the wiki and synthesize an answer from relevant pages
+---
+
+You are running `/hypo:query`. Answer a question by searching the wiki and synthesizing from relevant pages.
+
+## What this does
+
+- Searches `pages/` and `projects/` for pages relevant to the query
+- Reads and cross-references the top matches
+- Synthesizes a grounded answer citing `[[page-slug]]` links
+
+---
+
+## Step 1 — Understand the query
+
+Ask the user what they want to know if it was not provided in the command invocation.
+
+---
+
+## Step 2 — Locate package root and search
+
+Locate the Hypomnema package root (the directory containing this file's parent `commands/`).
+
+Run full-text search:
+
+```bash
+node <package-root>/scripts/query.mjs \
+  --q="<query terms>" \
+  [--hypo-dir="<path>"] \
+  [--limit=10]
+```
+
+---
+
+## Step 3 — Read relevant pages
+
+Read `index.md` first to understand the page catalog, then read the top-scoring pages returned by the search script (up to 5).
+
+---
+
+## Step 4 — Synthesize answer
+
+Write a clear, concise answer that:
+- Cites source pages as `[[slug]]` links
+- Notes confidence level if any source is speculative
+- Flags if no relevant pages were found ("Hypomnema does not currently have a page on this topic.")
+
+If the query surfaces a gap, offer to create a new page or run `/hypo:ingest` on a relevant source.
+
+---
+
+## Step 5 — Offer follow-ups
+
+After answering, suggest 1–2 related pages the user might want to read next.

package/commands/resume.md

@@ -0,0 +1,48 @@
+---
+description: Resume the most recent session for an active project
+---
+
+You are running `/hypo:resume`. Load the session state for an active project and pick up where you left off.
+
+## What this does
+
+- Reads `projects/<name>/session-state.md` (next tasks)
+- Reads `projects/<name>/hot.md` (what was done last session)
+- Offers to continue from the last stopping point
+
+---
+
+## Step 1 — Resolve project
+
+If the user named a project in the command invocation, use that. Otherwise, locate the Hypomnema package root and run:
+
+```bash
+node <package-root>/scripts/resume.mjs [--hypo-dir="<path>"] [--project=<name>]
+```
+
+The script will resolve the most recently active project from `hot.md` if `--project` is omitted.
+
+---
+
+## Step 2 — Present session state
+
+Show the output from the script:
+- **Project** name
+- **Next tasks** from `session-state.md`
+- **Background** from `hot.md` (what was done last session, condensed)
+
+---
+
+## Step 3 — Offer to continue
+
+After presenting the state, ask:
+
+> "Ready to pick up from here? Which task should we start with?"
+
+If the session-state lists numbered tasks, offer them as options. Start immediately once the user selects one.
+
+---
+
+## Step 4 — On completion of a task
+
+When a task is marked done, offer to update `session-state.md` to reflect the new state before closing.

package/commands/stats.md

@@ -0,0 +1,39 @@
+---
+description: Show statistics about the wiki
+---
+
+You are running `/hypo:stats`. Display a summary of wiki health and activity.
+
+## What this shows
+
+- Total page count, broken down by type
+- Number of projects and sources
+- ADR count
+- Date of last recorded activity
+
+---
+
+## Step 1 — Locate package root
+
+Locate the Hypomnema package root (the directory containing this file's parent `commands/`).
+
+If the user specified a Hypomnema directory, pass it as `--hypo-dir="<path>"`. Otherwise omit the flag.
+
+---
+
+## Step 2 — Run the stats script
+
+```bash
+node <package-root>/scripts/stats.mjs [--hypo-dir="<path>"] [--json]
+```
+
+---
+
+## Step 3 — Report results
+
+Show the output verbatim. Then add a brief health commentary:
+
+- If `sources` is 0: "No external sources yet — consider running `/hypo:ingest` with a document or URL."
+- If `missingFrontmatter` > 0: "N page(s) missing frontmatter — run `/hypo:lint` to identify them."
+- If `lastActivity` is more than 14 days ago: "Last activity was over 2 weeks ago — consider a `/hypo:crystallize` pass."
+- Otherwise: "Wiki looks active and healthy."

package/commands/uninstall.md

@@ -0,0 +1,52 @@
+---
+description: Remove Hypomnema hooks and clean up settings.json
+---
+
+You are running `/hypo:uninstall`. Remove Hypomnema from this machine.
+
+## What this does
+
+- Removes Hypomnema hook files from `~/.claude/hooks/` (and optionally `~/.codex/hooks/`)
+- Strips Hypomnema entries from `~/.claude/settings.json`, leaving all other hooks untouched
+- **Dry-run by default** — shows what would be removed without making any changes
+
+---
+
+## Step 1 — Confirm intent
+
+Say:
+> "This will remove Hypomnema hooks from your system. Your wiki files are NOT deleted.
+> Run in dry-run mode first to preview changes? [yes]"
+
+Default: yes (dry-run first)
+
+---
+
+## Step 2 — Dry run
+
+Run:
+```
+node scripts/uninstall.mjs
+```
+
+Show the output to the user. Ask:
+> "Proceed with removal? (yes / no)"
+
+If no → abort and confirm nothing was changed.
+
+---
+
+## Step 3 — Apply (if confirmed)
+
+```
+node scripts/uninstall.mjs --apply
+```
+
+If the user also wants Codex hooks removed, append `--codex`.
+
+---
+
+## Notes
+
+- Wiki content (`~/hypomnema/`) is never touched — only hook files and settings.json entries
+- To reinstall, run `/hypo:init`

package/commands/upgrade.md

@@ -0,0 +1,63 @@
+---
+description: Check for Hypomnema updates and optionally apply them
+---
+
+You are running `/hypo:upgrade`. Check if the installed Hypomnema wiki is out of date and offer to apply updates.
+
+## What this checks
+
+- **SCHEMA version**: compares `~/hypomnema/SCHEMA.md` version against the package's current version
+- **Hook files**: checks if any hooks in `~/.claude/hooks/` are stale or missing
+- **settings.json**: checks if all hook registrations are present in `~/.claude/settings.json`
+
+---
+
+## Step 1 — Locate package root
+
+Locate the Hypomnema package root (the directory containing this file's parent `commands/`).
+
+If the user specified a Hypomnema directory, pass it as `--hypo-dir="<path>"`. Otherwise omit the flag.
+
+---
+
+## Step 2 — Run upgrade check
+
+```bash
+node <package-root>/scripts/upgrade.mjs [--hypo-dir="<path>"]
+```
+
+Show the output verbatim.
+
+> **Note**: If a major SCHEMA bump is detected, this step generates a `MIGRATION-vX.Y.md` file in the Hypomnema root. This is a new informational file — no existing files are overwritten.
+
+---
+
+## Step 3 — Interpret and summarise
+
+- `✓` — up to date, no action needed
+- `⚠` — minor update available (stale hook or missing settings entry)
+- `✗` — major version bump or missing hook files (action required)
+
+For a **major SCHEMA bump**: point the user to the generated `MIGRATION-vX.Y.md` file in their Hypomnema root and ask them to review it before applying.
+
+---
+
+## Step 4 — Confirm before applying
+
+If there is anything to update, ask the user:
+
+> Updates found: [list what needs updating].
+> Apply now? Hook files will be overwritten and settings.json will be merged.
+> Note: SCHEMA.md is never auto-overwritten — update it manually after reviewing the diff. (y/N)
+
+- If **yes** → run with `--apply`:
+  ```bash
+  node <package-root>/scripts/upgrade.mjs [--hypo-dir="<path>"] --apply
+  ```
+- If **no** → tell the user they can apply later by running `/hypo:upgrade` again.
+
+---
+
+## Step 5 — Post-apply
+
+After applying, recommend running `/hypo:doctor` to verify the installation is healthy.

package/commands/verify.md

@@ -0,0 +1,60 @@
+---
+description: Check verify_by fields and surface overdue or missing verifications
+---
+
+You are running `/hypo:verify`. Audit wiki pages for overdue or missing `verify_by` fields.
+
+## What this does
+
+- Scans `pages/` and `projects/` for pages of types `adr`, `page`, `learning`, `concept`, `playbook`, `tool-eval`
+- Reports overdue pages (past `verify_by_date`), upcoming (within 14 days), and pages missing a `verify_by` question
+
+---
+
+## Step 1 — Locate package root and run
+
+Locate the Hypomnema package root (the directory containing this file's parent `commands/`).
+
+```bash
+node <package-root>/scripts/verify.mjs [--hypo-dir="<path>"] [--file=<path>]
+```
+
+Options:
+- `--file=<path>` — check a single page only (useful after editing a page)
+
+---
+
+## Step 2 — Report results
+
+Show the script output verbatim:
+- `✗ Overdue` — page is past its `verify_by_date`; requires immediate review
+- `⚠ Due soon` — within 14 days
+- `⚠ Missing verify_by` — tracked page has no verification question set
+- `✓` — all pages up to date
+
+---
+
+## Step 3 — Offer to review overdue pages
+
+For each overdue page, ask:
+
+> "[[<slug>]] is overdue for verification. The question was: '<verify_by>'. Is this still accurate?"
+
+If the user confirms it is still accurate:
+- Update `verify_by_date` to a new future date (suggest 90 days from today)
+
+If the user says it is outdated:
+- Help update the page content
+- Reset `verify_by_date` and optionally revise `verify_by`
+
+---
+
+## Step 4 — Add missing verify_by fields
+
+For pages missing `verify_by`, suggest a verification question based on the page type:
+- `concept` / `learning`: "Is this still the recommended approach?"
+- `playbook`: "Has this procedure been tested recently?"
+- `tool-eval`: "Is this evaluation still current? Check for a newer version."
+- `adr`: "Is this decision still in effect, or has it been superseded?"
+
+Ask the user to confirm the question, then add it to the frontmatter.