@drewpayment/mink 0.1.0 → 0.2.0

package/README.md

@@ -20,6 +20,7 @@ Mink intercepts these lifecycle events and maintains structured state so the ass
 - **Evaluate UI designs** with automated multi-viewport screenshots
 - **Advise on frameworks** with a decision tree and migration guides
 - **Build a cross-project wiki** that accumulates knowledge across all your projects
+- **Capture notes from anywhere** with an AI-powered Claude Code skill that categorizes, tags, and links notes automatically
 
 ## How It Works
 
@@ -59,16 +60,25 @@ All state lives in `~/.mink/` -- nothing is stored in your project repository.
 - **Built-in Tasks** — File index rescan, action log consolidation, waste detection, learning memory reflection, and project suggestions — all on configurable schedules
 
 ### Interfaces
-- **CLI** — 20+ commands covering lifecycle hooks, state management, scheduling, configuration, backup/restore, and more
+- **CLI** — 25+ commands covering lifecycle hooks, state management, notes/wiki, scheduling, configuration, backup/restore, and more
 - **Real-time Dashboard** — Web UI with 10 panels, SSE live updates, light/dark themes, virtual scrolling, and interactive charts
 
+### Notes & Wiki
+- **Wiki Vault** — Obsidian-compatible markdown vault that accumulates knowledge across all projects
+- **Note Capture** — `mink note` CLI captures notes from any directory into the vault
+- **Claude Code Skill** — `/mink:note` skill uses Claude as the AI brain for intelligent categorization, tagging, and wikilink insertion
+- **Daily Notes** — `mink note --daily` creates or appends to daily journal entries
+- **Vault Index** — Token-efficient file index for the vault, with search and tag aggregation
+- **Git Backup** — Auto-commit and push vault changes on session end
+- **Templates** — 6 built-in templates (quick-capture, daily, meeting, project, area, person)
+
 ### Advanced
 - **Design Evaluation** — Automated multi-viewport screenshot capture with server and route detection (uses Puppeteer)
 - **Framework Advisor** — Decision tree, framework catalog, comparison matrix, and migration prompts for UI framework selection
 
 ## Current Status
 
-Specs 1–14 are fully implemented and tested. Remaining specs (wiki, test plan) are designed and documented in `specs/`.
+Specs 1–15 are fully implemented and tested. The test plan spec (16) is designed and documented in `specs/`.
 
 | Domain | Specs | Status |
 |--------|-------|--------|
@@ -79,7 +89,7 @@ Specs 1–14 are fully implemented and tested. Remaining specs (wiki, test plan)
 | Automation | Background Scheduler | Implemented |
 | Interfaces | CLI Commands, Dashboard | Implemented |
 | Advanced | Design Evaluation, Framework Advisor | Implemented |
-| Wiki | Cross-Project Wiki | Designed |
+| Wiki | Cross-Project Wiki & Notes | Implemented |
 | Quality | Test Plan | Designed |
 
 ## Installation
@@ -93,10 +103,10 @@ Specs 1–14 are fully implemented and tested. Remaining specs (wiki, test plan)
 
 ```bash
 # With Bun (recommended)
-bun add -g mink
+bun add -g @drewpayment/mink
 
 # With npm
-npm install -g mink
+npm install -g @drewpayment/mink
 ```
 
 ### Initialize in a project
@@ -133,6 +143,159 @@ cat ~/.mink/projects/*/session.json
 
 You should see a fresh session state with a unique ID, timestamp, and zeroed counters.
 
+## Notes & Wiki
+
+Mink includes a notes and wiki system that builds a portable, Obsidian-compatible knowledge base across all your projects. Notes can be captured from any directory and are automatically organized into a structured vault.
+
+### Set up the vault
+
+```bash
+# Create a new vault (default: ~/.mink/wiki/)
+mink wiki init
+
+# Or point to an existing Obsidian vault / notes directory
+mink wiki init ~/dev/notes
+```
+
+This creates the vault structure, seeds templates, and builds a file index. If you point to an existing directory, Mink scans and indexes all markdown files without modifying them.
+
+### Capture notes
+
+The `mink note` command captures notes from any directory into your vault:
+
+```bash
+# Quick capture — lands in inbox/
+mink note "API rate limiting needs investigation"
+
+# Structured note with title and body
+mink note --title "JWT Cookie Pattern" --body "Use httpOnly cookies for token storage..."
+
+# Link to the current Mink project
+mink note --project my-api "Retry logic needs exponential backoff"
+
+# Daily journal
+mink note --daily "Had a breakthrough on the caching layer"
+mink note --daily                    # Create today's daily note (empty template)
+
+# From a template
+mink note --template meeting --title "Sprint Planning 2026-04-12"
+
+# With explicit category and tags
+mink note --category resources --tags "auth,security" --title "OAuth2 Flow Reference"
+
+# Ingest an existing file into the vault
+mink note --file ./scratch-notes.md --category resources
+```
+
+### Use the Claude Code skill
+
+The `/mink:note` skill is the recommended way to capture notes. It uses Claude as the AI brain to automatically determine category, tags, title, and wikilinks.
+
+```bash
+# Install the skill globally
+mink skill install
+```
+
+Then in any Claude Code session:
+
+```
+/mink:note I had a meeting with Sarah about the CMS migration timeline.
+           She wants to target Q3 for the cutover.
+```
+
+Claude will analyze the content, check existing notes for related topics and people, and run `mink note` with the right flags — placing the note in the correct category with tags and `[[wikilinks]]` to related notes.
+
+### Browse and search
+
+```bash
+# List recent notes
+mink note list --recent 10
+
+# Filter by category or tag
+mink note list --category projects
+mink note list --tag meeting
+
+# Full-text search
+mink note search "authentication"
+```
+
+### Vault structure
+
+```
+vault-root/
+  _index.md              # Master index (auto-maintained)
+  inbox/                  # Quick captures land here
+  projects/               # Project-linked notes + Mink-generated wiki pages
+    my-api/
+      overview.md         # Auto-created on mink init
+      sessions/           # Daily session summaries
+      *.md                # Your project notes
+  areas/                  # Ongoing responsibilities
+    daily/                # Daily notes (areas/daily/2026-04-12.md)
+  resources/              # Reference material
+  archives/               # Completed/inactive
+  templates/              # Note templates
+  patterns/               # Cross-project patterns
+```
+
+### Obsidian compatibility
+
+The vault is a standard markdown directory fully compatible with Obsidian:
+
+- **Wikilinks** — `[[Note Title]]` syntax for internal links
+- **YAML frontmatter** — `created`, `updated`, `tags`, `category` fields
+- **Graph view** — Wikilinks render as connections in Obsidian's knowledge graph
+- **Templates** — Compatible with Obsidian's Templater plugin (`{{variable}}` syntax)
+
+Open the vault directory as an Obsidian vault and everything works out of the box.
+
+### Git backup
+
+Enable automatic git backup to sync your vault across machines:
+
+```bash
+# Enable git backup
+mink config wiki.git-backup true
+
+# Set the remote (default: origin)
+mink config wiki.git-remote origin
+```
+
+When enabled, Mink auto-commits and pushes vault changes at the end of each session. Pushes are best-effort with a 10-second timeout — if the push fails, the local commit is preserved and will be included in the next push.
+
+### Hook integration
+
+When the wiki is enabled, Mink hooks automatically:
+
+- **On session start** — Report inbox count if notes need categorization
+- **On session end** — Write a session summary to `projects/{slug}/sessions/{date}.md`
+- **On `mink init`** — Create a project overview page in the vault
+
+### Configuration
+
+```bash
+# View all wiki/notes settings
+mink config
+
+# Set vault location
+mink config wiki.path ~/my-notes
+
+# Disable the wiki feature
+mink config wiki.enabled false
+
+# Set default category for CLI captures (default: inbox)
+mink config notes.default-category inbox
+```
+
+| Setting | Default | Env Override | Description |
+|---------|---------|-------------|-------------|
+| `wiki.path` | `~/.mink/wiki/` | `MINK_WIKI_PATH` | Vault directory |
+| `wiki.enabled` | `true` | `MINK_WIKI_ENABLED` | Toggle wiki feature |
+| `wiki.sync-mode` | `immediate` | `MINK_WIKI_SYNC_MODE` | Update timing |
+| `wiki.git-backup` | `false` | `MINK_WIKI_GIT_BACKUP` | Auto-commit and push |
+| `wiki.git-remote` | `origin` | `MINK_WIKI_GIT_REMOTE` | Git remote for push |
+| `notes.default-category` | `inbox` | `MINK_NOTES_DEFAULT_CATEGORY` | Default note category |
+
 ## Architecture
 
 ### State Directory
@@ -207,7 +370,7 @@ bun test tests/unit/session.test.ts
 ```
 mink/
 ├── src/
-│   ├── cli.ts                # Entry point, command routing (20+ commands)
+│   ├── cli.ts                # Entry point, command routing (25+ commands)
 │   ├── commands/             # CLI command implementations
 │   │   ├── init.ts           # mink init — runtime detection, hook wiring
 │   │   ├── session-start.ts  # Hook: create fresh session state
@@ -216,6 +379,9 @@ mink/
 │   │   ├── post-read.ts      # Hook: post-read tracking
 │   │   ├── pre-write.ts      # Hook: write enforcement
 │   │   ├── post-write.ts     # Hook: post-write tracking
+│   │   ├── wiki.ts           # Wiki vault management (init, status, rebuild, organize)
+│   │   ├── note.ts           # Note capture, list, and search
+│   │   ├── skill.ts          # Claude Code skill installer
 │   │   ├── status.ts         # Project health display
 │   │   ├── scan.ts           # Force full file index rescan
 │   │   ├── config.ts         # Global configuration management
@@ -250,15 +416,22 @@ mink/
 │   │   ├── dashboard-api.ts  # Dashboard REST API + SSE
 │   │   ├── design-eval/      # Screenshot capture, route/server detection
 │   │   ├── framework-advisor/ # Catalog, decision tree, migration prompts
+│   │   ├── vault.ts          # Wiki vault path resolution and structure
+│   │   ├── vault-templates.ts # Note template management
+│   │   ├── note-writer.ts    # Note creation, frontmatter, daily notes
+│   │   ├── note-linker.ts    # Wikilink extraction, insertion, backlinks
+│   │   ├── note-index.ts     # Vault file index with search
 │   │   └── ...               # Global config, backup, reflection, etc.
 │   ├── dashboard/            # Embedded dashboard UI (HTML/CSS/JS generation)
 │   │   ├── get-dashboard-html.ts  # Main HTML assembly
 │   │   ├── panel-*.ts        # 10 panel implementations
 │   │   ├── css-*.ts          # Base styles and themes
 │   │   └── js-*.ts           # Charts, SSE, virtual scroll, search
+│   ├── skills/               # Claude Code skill files
+│   │   └── mink-note.md      # /mink:note skill for intelligent note capture
 │   └── types/                # TypeScript interfaces
 ├── tests/
-│   ├── unit/                 # 35+ unit test files
+│   ├── unit/                 # 40+ unit test files
 │   └── integration/          # 15+ integration test files
 ├── specs/                    # Feature specifications (technology-agnostic)
 └── docs/                     # Design docs and implementation plans
@@ -310,6 +483,16 @@ bun src/cli.ts status
 
 # Run a waste detection scan
 bun src/cli.ts detect-waste
+
+# Set up the wiki vault and capture notes
+bun src/cli.ts wiki init
+bun src/cli.ts note "Testing the notes feature"
+bun src/cli.ts note --daily "Today I worked on mink"
+bun src/cli.ts note list --recent 5
+bun src/cli.ts note search "testing"
+
+# Install the Claude Code skill
+bun src/cli.ts skill install
 ```
 
 ### Adding a new spec implementation
@@ -339,7 +522,7 @@ Each spec follows this workflow:
 | 12 | [Dashboard](./specs/12-dashboard.md) | Interface | Implemented |
 | 13 | [Design Evaluation](./specs/13-design-evaluation.md) | Advanced | Implemented |
 | 14 | [Framework Advisor](./specs/14-framework-advisor.md) | Advanced | Implemented |
-| 15 | [Cross-Project Wiki](./specs/15-cross-project-wiki.md) | Wiki | Designed |
+| 15 | [Cross-Project Wiki](./specs/15-cross-project-wiki.md) | Wiki | Implemented |
 | 16 | [Test Plan](./specs/16-test-plan.md) | Quality | Designed |
 
 ## License