hypomnema 1.0.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "hypomnema",
+  "version": "1.0.0",
+  "description": "LLM-native personal wiki system — session-aware knowledge base for Claude Code",
+  "author": {
+    "name": "sk-lim19f",
+    "email": "limsangkyu0219@gmail.com"
+  },
+  "commands": "./commands/",
+  "skills": "./skills/"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sk-lim19f
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,160 @@
+[English](README.md) | 한국어
+
+---
+
+# Hypomnema
+
+Claude Code를 위한 LLM 네이티브 개인 위키 시스템.
+
+Hypomnema는 Claude Code를 복리적으로 성장하는 지식 베이스로 만들어줍니다. 소스를 그대로 청크 단위로 저장하는 대신, LLM이 각 소스를 읽고 합성하여 기존 페이지를 업데이트합니다. 새 소스가 지식을 추가하는 것보다 기존 지식을 강화하는 방향으로 동작합니다.
+
+---
+
+## 빠른 시작
+
+```bash
+npm install -g hypomnema   # 또는: npx hypomnema
+```
+
+Claude Code에서 실행:
+
+```
+/hypo:init
+```
+
+위키 디렉터리를 생성하고, 훅을 설치하며, `~/.claude/settings.json`에 병합합니다.
+
+---
+
+## Git 동기화
+
+`/hypo:init` 실행 후 위키 디렉터리는 이미 로컬 git 저장소입니다. 여러 기기에서 동기화하려면 remote를 추가하고 push하세요:
+
+```bash
+git -C ~/hypomnema remote add origin <저장소-URL>
+git -C ~/hypomnema push -u origin HEAD
+```
+
+이후 Stop 훅이 매 세션 종료 시 자동으로 commit 및 push합니다 — 별도 동기화 작업이 필요 없습니다.
+
+---
+
+## Hypomnema를 선택하는 이유
+
+| | Hypomnema | Obsidian / Notion | RAG / 벡터 검색 |
+|---|---|---|---|
+| **캡처 노력** | URL 붙여넣기 → 완료 | 직접 노트 작성 | 업로드 + 임베딩 파이프라인 |
+| **지식 성장** | 새 소스가 기존 페이지를 업데이트 | 각 노트가 독립적 | 청크가 무한정 늘어남 |
+| **검색** | LLM이 근거 있는 답변 합성 | 전문 검색 | 최근접 이웃 청크 |
+| **워크플로 통합** | Claude Code 내부에서 동작 | 별도 앱 / 브라우저 탭 | 별도 서비스 |
+
+네 가지 핵심 차별점:
+
+1. **저장이 아닌 합성.** Claude가 각 소스를 읽고 구조화된 페이지로 합성합니다. 단순 복사·붙여넣기가 아니라, 추론할 수 있는 지식 베이스를 얻게 됩니다.
+2. **복리 성장 페이지.** 새 소스가 기존 페이지와 겹치면 Claude가 해당 페이지를 업데이트합니다. 위키는 단순히 커지는 것이 아니라 더 촘촘하고 연결되어 성장합니다.
+3. **무마찰 훅.** 세션 시작·종료, 자동 스테이징, 자동 커밋이 Claude Code 라이프사이클 훅을 통해 자동으로 실행됩니다. 위키 관리를 위해 컨텍스트 전환이 필요 없습니다.
+4. **워크플로 네이티브.** 별도 앱, 내보내기/가져오기, 동기화 서비스가 없습니다. 이미 열려 있는 Claude Code 세션 안에서 동작합니다.
+
+---
+
+## 시나리오
+
+**A — 새 기술 학습**
+Kubernetes 문서와 블로그 글을 읽고 있습니다. 각 URL을 `/hypo:ingest`에 넣으면 됩니다. 세 번째 글을 처리할 때쯤 Claude는 새 페이지를 만드는 대신 기존 `kubernetes-networking.md`를 업데이트합니다. 일주일 후 `/hypo:query "pod CIDR 할당은 어떻게 동작하나요?"`를 실행하면 자신의 노트를 인용한 합성 답변을 받을 수 있습니다.
+
+**B — 엔지니어링 결정 추적**
+중요한 변경 사항을 머지하기 전에 설계 문서나 PR 설명을 `/hypo:ingest`로 처리합니다. Claude가 컨텍스트, 트레이드오프, 결정 사항을 담은 ADR 스타일 페이지를 만듭니다. 이후 `[[wikilink]]` 참조가 관련 프롬프트에 근거를 직접 주입합니다.
+
+**C — 연구 누적**
+몇 주에 걸쳐 특정 주제의 논문들을 읽고 있습니다. 각 `/hypo:ingest` 실행이 논문을 합성하고 기존 페이지와 교차 연결합니다. 언제든 `/hypo:query`를 실행하면 자신의 노트에 근거한 문헌 리뷰 스타일의 요약을 얻을 수 있습니다.
+
+**D — AI 행동 튜닝**
+Claude가 잘못하거나 정확히 맞았을 때마다 `/hypo:feedback`을 실행합니다. 교정 사항이 `pages/feedback/`에 저장되고 세션 시작 시 주입되어, 같은 실수가 반복되지 않습니다 — 하나의 대화가 아닌 세션 간에 걸쳐서요.
+
+**E — 일시 중단된 프로젝트 재개**
+3주 동안 프로젝트를 손 놓았습니다. 다음 세션 시작 시 훅이 `projects/<name>/session-state.md`를 읽고 "다음 작업"과 최근 결정 사항을 컨텍스트에 주입합니다. 첫 번째 프롬프트를 입력하기 전에 이미 업무 파악이 완료됩니다.
+
+---
+
+## 작동 방식
+
+1. **인제스트** — 문서, URL, 또는 텍스트를 `/hypo:ingest`에 붙여넣습니다. Claude가 원본 소스를 저장하고 구조화된 페이지로 합성합니다.
+2. **쿼리** — `/hypo:query`에 무엇이든 질문합니다. Claude가 페이지를 검색하고 `[[wikilink]]` 인용과 함께 근거 있는 답변을 합성합니다.
+3. **세션 종료** — 세션 종료 시 Claude가 `session-state.md`(다음 작업)와 `hot.md`(완료 내용)를 업데이트하여 다음 세션이 원활하게 재개됩니다.
+4. **복리 가치** — 시간이 지날수록 새 소스가 기존 페이지를 업데이트하며 위키가 더 촘촘하고 유용해집니다.
+
+---
+
+## 위키에 저장할 것 / 저장하지 말 것
+
+**저장할 것:**
+- 외부 소스(문서, 논문, 강연)에서 합성된 지식
+- 아키텍처 결정과 근거
+- AI 행동 교정 및 선호사항
+- git에 담기 어려운 프로젝트 컨텍스트 (이해관계자 제약, 미결 질문, 배경)
+- 연구 결과 및 교차 소스 비교
+
+**저장하지 말 것:**
+- 원본 소스 자료 — `sources/`에 자동으로, 미편집 상태로 저장됨
+- 자격증명, 토큰, 비밀 — `.hypoignore`로 민감한 경로 제외
+- 현재 세션의 일시적 작업 목록 — 대화 내 작업 목록 사용
+- 레포지토리에서 도출 가능한 코드 패턴 — `git log`와 `grep`이 이미 정규 소스
+- 다른 곳에 정규 소유자가 있는 정보 (Jira 티켓, Confluence 페이지, API 문서) — 미러가 아닌 *합성본*을 인제스트
+
+---
+
+## 명령어
+
+| 명령어 | 설명 |
+|--------|------|
+| `/hypo:init` | 새 위키 설정 |
+| `/hypo:doctor` | 상태 점검 |
+| `/hypo:upgrade` | 훅을 최신 버전으로 업그레이드 |
+| `/hypo:uninstall` | 훅 및 등록 정보 제거 |
+| `/hypo:ingest` | 외부 소스를 위키에 인제스트 |
+| `/hypo:query` | 위키 페이지에서 검색 및 답변 합성 |
+| `/hypo:crystallize` | 초안 및 관련 페이지를 안정적 지식으로 통합 |
+| `/hypo:resume` | 활성 프로젝트의 가장 최근 세션 재개 |
+| `/hypo:feedback` | AI 행동 교정 사항 기록 |
+| `/hypo:verify` | 만료되었거나 누락된 `verify_by` 필드 감사 |
+| `/hypo:stats` | 위키 통계 표시 |
+| `/hypo:graph` | 위키링크 의존성 그래프 생성 |
+| `/hypo:lint` | 프론트매터 및 위키링크 유효성 검사 |
+
+---
+
+## 디렉터리 구조
+
+```
+<wiki-root>/
+├── hypo-config.md      ← 루트 마커 + 설정
+├── index.md            ← 검색 가능한 페이지 카탈로그
+├── hot.md              ← 활성 프로젝트 포인터
+├── log.md              ← 추가 전용 활동 로그
+├── SCHEMA.md           ← 타입 시스템 참조
+├── hypo-guide.md       ← 운영 가이드
+├── .hypoignore         ← 훅에서 제외할 글로브 패턴
+├── pages/              ← 영구 지식 페이지
+├── projects/           ← 프로젝트 아티팩트 및 세션 로그
+└── sources/            ← 원본 인제스트 소스 (수정 금지)
+```
+
+---
+
+## 요구 사항
+
+- Node.js ≥ 18
+- Claude Code CLI
+
+---
+
+## 문서
+
+- [ARCHITECTURE.md](docs/ARCHITECTURE.md) — 내부 구조, 컴포넌트 맵, 데이터 흐름
+- [CONTRIBUTING.md](docs/CONTRIBUTING.md) — 개발 환경 설정, 컨벤션, PR 프로세스
+
+---
+
+## 라이선스
+
+MIT

package/README.md

@@ -0,0 +1,160 @@
+English | [한국어](README.ko.md)
+
+---
+
+# Hypomnema
+
+LLM-native personal wiki system for Claude Code.
+
+Hypomnema turns Claude Code into a compounding knowledge base. Instead of chunking sources as-is, an LLM reads each source, synthesizes it, and updates existing pages — so new sources update knowledge more than they create it.
+
+---
+
+## Quick start
+
+```bash
+npm install -g hypomnema   # or: npx hypomnema
+```
+
+In Claude Code, run:
+
+```
+/hypo:init
+```
+
+This sets up your wiki directory, installs hooks, and merges them into `~/.claude/settings.json`.
+
+---
+
+## Git sync
+
+After `/hypo:init`, your wiki directory is already a local git repository. To sync it across machines, add a remote and push:
+
+```bash
+git -C ~/hypomnema remote add origin <your-repo-url>
+git -C ~/hypomnema push -u origin HEAD
+```
+
+The Stop hook then auto-commits and pushes your wiki at the end of every session — no manual sync needed.
+
+---
+
+## Why Hypomnema
+
+| | Hypomnema | Plain Obsidian / Notion | RAG / vector search |
+|---|---|---|---|
+| **Capture effort** | Paste a URL → done | Manual note-taking | Upload + embed pipeline |
+| **Knowledge growth** | New sources update existing pages | Each note is independent | Chunks multiply indefinitely |
+| **Retrieval** | LLM synthesizes a grounded answer | Full-text search | Nearest-neighbour chunks |
+| **Workflow integration** | Lives inside Claude Code | Separate app / browser tab | Separate service |
+
+Four things that set it apart:
+
+1. **Synthesis over storage.** Claude reads each source and synthesizes it into a structured page — not a copy-paste dump. You get a knowledge base you can reason over, not a pile of bookmarks.
+2. **Compounding pages.** When a new source overlaps an existing page, Claude updates that page. The wiki gets denser and more connected over time rather than just bigger.
+3. **Zero-friction hooks.** Session start, session close, auto-staging, and auto-commit happen automatically through Claude Code lifecycle hooks. You never context-switch to manage the wiki.
+4. **Native to your workflow.** No separate app, no export/import, no third-party sync service. Hypomnema runs inside the Claude Code session you already have open.
+
+---
+
+## Scenarios
+
+**A — Learning a new technology**
+You're reading Kubernetes docs and blog posts. Drop each URL into `/hypo:ingest`. By the third article, Claude is updating your existing `kubernetes-networking.md` page rather than creating another one. A week later, `/hypo:query "how does pod CIDR allocation work?"` returns a synthesized answer citing your own notes.
+
+**B — Tracking engineering decisions**
+Before merging a significant change, run `/hypo:ingest` on the design doc or PR description. Claude creates an ADR-style page with context, tradeoffs, and the decision. Future `[[wikilink]]` references pull the rationale directly into any prompt that asks about it.
+
+**C — Research accumulation**
+You're working through papers on a topic over several weeks. Each `/hypo:ingest` run synthesizes the paper and cross-links it to related pages you already have. At any point, `/hypo:query` gives you a literature-review-style summary grounded in your own notes.
+
+**D — Tuning AI behavior**
+Run `/hypo:feedback` whenever Claude does something wrong or exactly right. The correction is stored in `pages/feedback/` and injected at session start, so the same mistake doesn't happen twice — across sessions, not just within one conversation.
+
+**E — Resuming a paused project**
+You put a project down for three weeks. At the next session start, the hook reads `projects/<name>/session-state.md` and injects "next tasks" and recent decisions directly into context. You're back up to speed before you type the first prompt.
+
+---
+
+## How it works
+
+1. **Ingest** — drop a document, URL, or paste text into `/hypo:ingest`. Claude saves the raw source and synthesizes it into a structured page.
+2. **Query** — ask `/hypo:query` anything. Claude searches your pages and synthesizes a grounded answer with `[[wikilink]]` citations.
+3. **Session close** — on session end, Claude updates `session-state.md` (next tasks) and `hot.md` (what was done) so the next session resumes seamlessly.
+4. **Compound value** — over time, new sources update existing pages rather than creating new ones. The wiki gets denser and more useful.
+
+---
+
+## What goes in your wiki
+
+**Store here:**
+- Synthesized knowledge from external sources (docs, papers, talks)
+- Architecture decisions and their rationale
+- AI behavior corrections and preferences
+- Project context that doesn't belong in git (stakeholder constraints, open questions, background)
+- Research findings and cross-source comparisons
+
+**Do not store here:**
+- Raw source material — that goes in `sources/` automatically, unedited
+- Credentials, tokens, or secrets — use `.hypoignore` to exclude sensitive paths
+- Transient task lists for the current session — use the task list in the conversation
+- Code patterns derivable from the repo itself — `git log` and `grep` are already authoritative
+- Information that has a canonical owner elsewhere (Jira tickets, Confluence pages, API docs) — ingest a *synthesis*, not a mirror
+
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/hypo:init` | Set up a new wiki |
+| `/hypo:doctor` | Health check |
+| `/hypo:upgrade` | Upgrade hooks to latest version |
+| `/hypo:uninstall` | Remove hooks and registrations |
+| `/hypo:ingest` | Ingest an external source into the wiki |
+| `/hypo:query` | Search and synthesize an answer from wiki pages |
+| `/hypo:crystallize` | Consolidate drafts and related pages into stable knowledge |
+| `/hypo:resume` | Resume the most recent session for an active project |
+| `/hypo:feedback` | Record an AI behavior correction |
+| `/hypo:verify` | Audit pages for overdue or missing `verify_by` fields |
+| `/hypo:stats` | Show wiki statistics |
+| `/hypo:graph` | Generate a wikilink dependency graph |
+| `/hypo:lint` | Validate frontmatter and wikilinks |
+
+---
+
+## Directory layout
+
+```
+<wiki-root>/
+├── hypo-config.md      ← root marker + settings
+├── index.md            ← searchable page catalog
+├── hot.md              ← active project pointers
+├── log.md              ← append-only activity log
+├── SCHEMA.md           ← type system reference
+├── hypo-guide.md       ← operations guide
+├── .hypoignore         ← glob patterns excluded from hooks
+├── pages/              ← permanent knowledge pages
+├── projects/           ← project artifacts and session logs
+└── sources/            ← raw ingested sources (never edit)
+```
+
+---
+
+## Requirements
+
+- Node.js ≥ 18
+- Claude Code CLI
+
+---
+
+## Docs
+
+- [ARCHITECTURE.md](docs/ARCHITECTURE.md) — internals, component map, data flows
+- [CONTRIBUTING.md](docs/CONTRIBUTING.md) — development setup, conventions, PR process
+
+---
+
+## License
+
+MIT

package/commands/crystallize.md

@@ -0,0 +1,116 @@
+---
+description: Crystallize draft notes into stable knowledge — also the session-close alias
+---
+
+You are running `/hypo:crystallize`. This command serves two purposes:
+
+1. **Session close** — if invoked at the end of a session, run the session-close checklist first
+2. **Knowledge synthesis** — consolidate draft or scattered wiki pages into stable, well-linked pages
+
+---
+
+## Step 1 — Detect context
+
+If the user invoked `/hypo:crystallize` to close a session (phrases like "세션 종료", "오늘 작업 마무리", "session close", or "wrap up"), run Steps 2–3 (session-close checklist) **before** the synthesis scan. Otherwise skip to Step 4.
+
+---
+
+## Step 2 — Session-close checklist
+
+Work through each item in order. For an explicit session-close invocation, proceed automatically without asking for confirmation on each item.
+
+1. **session-state.md** — update `projects/<name>/session-state.md` with the next tasks list for the upcoming session (what to tackle first next time).
+2. **hot.md (project)** — update `projects/<name>/hot.md` with a session snapshot: what changed and decisions made. Keep under 500 words. Do not put next-step tasks here; those belong in session-state.md.
+3. **hot.md (root)** — update `<hypo-root>/hot.md` active-projects pointer table: set the `Last Session` date for this project to today.
+4. **session-log** — append a session entry to `projects/<name>/session-log/YYYY-MM.md` (create the file if it does not exist for this month).
+5. **open-questions** — only if `pages/open-questions.md` exists and questions were raised or resolved this session: move resolved ones out; add newly raised ones. Skip if unchanged.
+6. **log.md** — append a `session` entry to `<hypo-root>/log.md`.
+
+---
+
+## Step 3 — Session-close confirmation
+
+After completing the checklist, report:
+
+- ✓ session-state.md updated
+- ✓ hot.md (project + root) updated
+- ✓ session-log entry appended
+- ✓ open-questions updated (or skipped if unchanged)
+- ✓ log.md updated
+
+Then ask: "Session closed. Would you like to also run knowledge synthesis now, or stop here?"
+
+If the user says stop, end here. Otherwise continue to Step 4.
+
+---
+
+## Step 4 — Surface synthesis candidates
+
+Locate the Hypomnema package root (the directory containing this file's parent `commands/`).
+
+```bash
+node <package-root>/scripts/crystallize.mjs [--hypo-dir="<path>"] [--min-group=2]
+```
+
+Show the output to the user. If no candidates are found, tell them Hypomnema looks well-connected and no crystallization is needed.
+
+---
+
+## Step 5 — Choose what to crystallize
+
+If candidates exist, ask:
+
+> "Which would you like to crystallize?
+> 1. A tag cluster (synthesize related pages into one synthesis page)
+> 2. A draft page (upgrade to stable)
+> 3. Unlinked pages (add cross-links)"
+
+---
+
+## Step 5a — Tag cluster synthesis
+
+For a tag cluster:
+
+1. Read all pages in the cluster
+2. Create `pages/syntheses/<topic>.md` with `type: synthesis`
+3. Frontmatter:
+   ```yaml
+   ---
+   title: "<synthesis title>"
+   type: synthesis
+   updated: YYYY-MM-DD
+   tags: [<shared tags>]
+   confidence: high
+   ---
+   ```
+4. Body: synthesize key insights across the cluster, cite each source page with `[[slug]]`
+5. Add back-links: add `[[syntheses/<topic>]]` to each constituent page's "See also" section
+6. Update `index.md`
+
+---
+
+## Step 5b — Draft upgrade
+
+For a draft page:
+
+1. Read the draft
+2. Fill in any missing sections, improve clarity, add cross-links
+3. Change `tags: [draft]` → remove `draft` tag, set `confidence: high`
+4. Update `updated:` to today
+
+---
+
+## Step 5c — Cross-link unlinked pages
+
+For unlinked pages:
+
+1. Read each unlinked page
+2. Search the wiki for related pages (run `/hypo:query` mentally on the page title/tags)
+3. Add a `## See also` section with `[[slug]]` links to 2–3 related pages
+4. Reciprocally add links back where natural
+
+---
+
+## Step 6 — Report
+
+Show what was created or modified, and offer to run `/hypo:lint` to verify all new links resolve.

package/commands/doctor.md

@@ -0,0 +1,66 @@
+---
+description: Health check for a Hypomnema wiki installation
+---
+
+You are running `/hypo:doctor`. Verify the health of the current Hypomnema wiki installation.
+
+## What this checks
+
+- Wiki root directory exists and has `hypo-config.md` marker
+- Required subdirectories and baseline files are present
+- Claude Code hook files are installed in `~/.claude/hooks/`
+- `~/.claude/settings.json` contains all required hook registrations
+- Git repository and remote origin are configured
+- No broken `[[wiki-link]]` references
+- No overdue or missing `verify_by` fields on tracked pages
+
+---
+
+## Step 1 — Locate package root and resolve Hypomnema directory
+
+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: `HYPO_DIR` env → `hypo-config.md` scan → `~/hypomnema` default.
+
+---
+
+## Step 2 — Run the doctor script
+
+```bash
+node <package-root>/scripts/doctor.mjs [--hypo-dir="<path>"] [--json]
+```
+
+- `--hypo-dir=<path>` — override Hypomnema root (takes precedence over `HYPO_DIR` env and auto-scan)
+- `--json` — output results as a JSON array (useful for programmatic use)
+
+---
+
+## Step 3 — Report results
+
+Show the script output verbatim. Each line is prefixed with:
+- `✓` — check passed
+- `⚠` — warning (not blocking, but worth fixing)
+- `✗` — failure (installation is broken)
+
+Then show the summary line: `Result: N passed, N warnings, N failed`
+
+---
+
+## Step 4 — Recommend fixes
+
+For any `✗` failures:
+- Missing Hypomnema root or required directories/files → run `/hypo:init`.
+- 0 hook files installed → run `/hypo:init`.
+- 0 hook registrations in settings.json → run `/hypo:init`.
+
+For `⚠` warnings:
+- Missing `hypo-config.md` → run `/hypo:init` — it creates the config marker.
+- Missing baseline files (`index.md`, `hot.md`, etc.) → run `/hypo:init`.
+- Partial hook files (some missing) → run `/hypo:init` to install missing hooks.
+- Partial settings.json registrations → run `/hypo:init` to merge missing entries.
+- Missing git remote → `git -C <hypo-dir> remote add origin <url>`.
+- Broken `[[links]]` → list the affected files and ask if the user wants to fix them now.
+- Overdue `verify_by_date` → offer to open the affected pages for review.
+- Missing `verify_by` question → suggest adding a `verify_by` field to the listed pages.
+
+If all checks passed, tell the user Hypomnema is healthy and ready to use.

package/commands/feedback.md

@@ -0,0 +1,67 @@
+---
+description: Record an AI behavior correction or preference into the wiki
+---
+
+You are running `/hypo:feedback`. Capture a behavior correction or preference into `pages/feedback/` for future sessions.
+
+## What this does
+
+- Creates or updates `pages/feedback/<topic>.md` with a dated entry
+- Appends a reference to `log.md`
+- Ensures the feedback is findable in future sessions
+
+---
+
+## Step 1 — Gather feedback details
+
+If the user did not provide them, ask:
+
+1. **Topic** (slug): "What topic does this feedback apply to? (e.g. `response-length`, `commit-style`, `code-comments`)"
+2. **Rule**: "State the rule or correction in one or two sentences."
+3. **Why** (optional): "What was the reason or incident that prompted this?"
+
+---
+
+## Step 2 — List existing feedback (optional)
+
+To check for an existing topic, locate the Hypomnema package root and run:
+
+```bash
+node <package-root>/scripts/feedback.mjs --list [--hypo-dir="<path>"]
+```
+
+If a matching topic exists, confirm with the user whether to append to it or create a new one.
+
+---
+
+## Step 3 — Write the feedback entry
+
+Compose the entry text. Format:
+
+```
+**Rule**: <one-line rule>
+
+**Why**: <reason or incident>
+
+**How to apply**: <when this kicks in>
+```
+
+Then run:
+
+```bash
+node <package-root>/scripts/feedback.mjs \
+  --topic="<slug>" \
+  --entry="<formatted entry text>" \
+  [--hypo-dir="<path>"] \
+  [--dry-run]
+```
+
+Run with `--dry-run` first to preview, then without it to write.
+
+---
+
+## Step 4 — Confirm and cross-reference
+
+After writing:
+- Tell the user: "Saved to `pages/feedback/<topic>.md`."
+- If this feedback should also update the project's `session-state.md` or the user's CLAUDE.md `<learned_behaviors>`, ask: "Should I also add this to your CLAUDE.md learned behaviors?"

package/commands/graph.md

@@ -0,0 +1,54 @@
+---
+description: Generate a wikilink dependency graph for the wiki
+---
+
+You are running `/hypo:graph`. Generate a link dependency graph from wiki pages.
+
+## What this does
+
+- Scans `pages/` and `projects/` for all `.md` files
+- Extracts `[[wikilink]]` references between pages
+- Outputs an adjacency graph in JSON, Mermaid, or DOT format
+
+---
+
+## 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 graph script
+
+```bash
+node <package-root>/scripts/graph.mjs \
+  [--hypo-dir="<path>"] \
+  [--format=json|mermaid|dot] \
+  [--min-edges=<n>]
+```
+
+Options:
+- `--format=json` (default) — adjacency list with in/out degree counts
+- `--format=mermaid` — Mermaid `graph TD` diagram (paste into a Markdown code block)
+- `--format=dot` — Graphviz DOT format
+- `--min-edges=<n>` — only include nodes with at least N total edges
+
+---
+
+## Step 3 — Present results
+
+- For **JSON**: summarise the top 10 most-connected nodes (highest in+out degree), then offer to show the full output.
+- For **Mermaid**: wrap the output in a `\`\`\`mermaid` code block so it renders in the chat.
+- For **DOT**: show the raw output and suggest pasting it into a Graphviz renderer.
+
+If `--min-edges` was not specified and there are more than 50 nodes, suggest re-running with `--min-edges=2` to focus on well-connected pages.
+
+---
+
+## Step 4 — Insights
+
+After displaying results, offer one or two observations:
+- Pages with high in-degree are hub pages — consider linking to them from new pages.
+- Pages with zero edges are isolated — suggest adding cross-links or running `/hypo:crystallize`.