@tyroneross/bookmark 0.2.0 → 0.3.2

package/README.md

@@ -21,121 +21,146 @@ This creates a painful pattern: every new session starts with you re-explaining
 
 ## How Bookmark Works
 
-**Install it. Forget about it. It just works.**
-
-Bookmark runs as an external process — zero tokens consumed from your context window. Four hooks handle everything automatically:
+Bookmark runs as a small external process. Four hooks keep a durable handoff current:
 
 | Hook | When | What |
 |------|------|------|
-| **PreCompact** | Before context compaction | Captures full context before it's compressed |
+| **PreCompact** | Before context compaction | Captures a mechanical file/tool checkpoint |
 | **SessionStart** | New session begins | Restores prior context so Claude knows what you were doing |
-| **UserPromptSubmit** | Every user message | Checks if a time-based snapshot is due |
-| **Stop** | Session ends | Final snapshot preserving everything |
+| **UserPromptSubmit** | Every user message | Checks time and token thresholds; alerts at 75% used |
+| **Stop** | Session ends | Captures files and requires a fresh semantic handoff |
 
 When you open a new terminal and run `claude`, Bookmark restores your prior context. Claude greets you knowing what you were working on, what decisions were made, and what's left to do.
 
 ## What Gets Captured
 
-Each snapshot extracts from the conversation transcript — no LLM calls needed:
+Bookmark separates reliable mechanical evidence from semantic judgment:
+
+- **`bookmark.context.md`** — Claude writes the current task, status, remaining work,
+  decisions, risks, open questions, sources of truth, and next steps.
+- **JSON snapshots and `LATEST.md`** — Bookmark extracts file changes, tool counts,
+  capture reason, model, and measured context usage from the transcript.
+
+The per-prompt threshold check makes no API call and reads only the transcript tail. Full
+transcript parsing runs only when an interval or threshold capture is due. The semantic handoff
+is capped at 800 tokens and points to source files instead of copying them.
 
-- **Decisions made** — "chose Postgres over SQLite because...", "going with React Query for..."
-- **Current status** — what was being worked on when the session ended
-- **Open items** — TODOs, next steps, unfinished work
-- **Unknowns and blockers** — things that were unclear or blocking progress
-- **Files changed** — which files were created, edited, or read
-- **Errors encountered** — what broke and whether it was resolved
-- **Tool usage** — aggregate counts of Read, Edit, Bash, etc.
+### File paths in snapshots are now project-relative
 
-All extraction uses pattern matching on the transcript. Zero API calls, zero cost, zero latency.
+As of v0.3.3, file paths in `.bookmark/snapshots/SNAP_*.json` are stored
+relative to `project_path` (e.g. `src/foo.ts` instead of
+`/Users/me/dev/git-folder/myapp/src/foo.ts`). Older snapshots may carry
+pre-move absolute paths that went stale when a project was relocated
+(e.g. `~/Desktop/git-folder/...` → `~/dev/git-folder/...`); those are not
+auto-rewritten — they're left intact so the historical record stays
+honest. Going forward, a project move only invalidates `project_path`
+itself, not the per-file entries inside each snapshot.
 
 ## Install
 
-**In a project (recommended):**
+**Via Claude Code plugin marketplace (recommended):**
 
 ```bash
-npm install @tyroneross/bookmark
+/plugin marketplace add tyroneross/bookmark
+/plugin install bookmark@bookmark
 ```
 
-Hooks are configured automatically. Start a Claude Code session and you're covered.
-
-**Globally:**
+**Via npm (in a project):**
 
 ```bash
-npm install -g @tyroneross/bookmark
+npm install @tyroneross/bookmark
 ```
 
-Then activate in any project by typing `/bookmark:activate` in a Claude Code session, or run `bookmark setup` in your project directory.
+Hooks are configured automatically. Start a Claude Code session and you're covered.
 
-**As a Claude Code plugin:**
+**Via npm (globally):**
 
 ```bash
-claude plugin add github.com/tyroneross/bookmark
+npm install -g @tyroneross/bookmark
 ```
 
+Then activate in any project by running `bookmark setup` in your project directory.
+
 ## Commands
 
 Use these inside Claude Code:
 
 | Command | What it does |
 |---------|-------------|
+| `/bookmark` | Show current session context and bookmark status; forwards any arguments to the bookmark CLI |
 | `/bookmark:snapshot` | Take a manual snapshot right now |
 | `/bookmark:restore` | Restore from latest or a specific snapshot |
 | `/bookmark:status` | Show snapshot count, compaction cycles, last snapshot time |
 | `/bookmark:list` | List available snapshots with details |
-| `/bookmark:activate` | Set up Bookmark for the current project |
 
 ## CLI
 
 ```bash
 bookmark status              # Show stats
+bookmark snapshot            # Take a manual snapshot now
 bookmark list                # List snapshots
 bookmark show --latest       # Show latest snapshot content
 bookmark show SNAP_ID        # Show specific snapshot
 bookmark config              # Show current configuration
 bookmark config --interval 15  # Change snapshot interval to 15 minutes
+bookmark config --token-threshold 75  # Capture and alert at 75% used
+bookmark config --context-limit 500000  # Override model context limit
 bookmark setup               # Interactive configuration
 ```
 
-## Adaptive Thresholds
+## Token Threshold Capture
 
-Bookmark gets smarter the more your context compacts. It tracks compaction cycles and adjusts when snapshots trigger:
+Bookmark reads the latest model-reported usage from the Claude Code transcript. It counts input,
+cache-read, cache-write, output, and the pending prompt against the active model's context limit.
+At 75% used, Bookmark captures a `token_threshold` snapshot, shows a warning, asks Claude to
+refresh `bookmark.context.md`, and recommends a new session. It alerts once until a new session
+or lower post-compaction usage re-arms the threshold.
 
-| Compaction count | Snapshot triggers at | Behavior |
-|-----------------|---------------------|----------|
-| 0 (never compacted) | 20% context remaining | Conservative — only near compaction |
-| 1 (once) | 30% remaining | Earlier snapshots |
-| 2 (twice) | 40% remaining | Even earlier |
-| 3+ (frequent) | 50% remaining | Aggressive — snapshot at halfway |
+Bookmark resolves context limits only for model IDs documented by Anthropic. If the transcript
+reports an unknown model, Bookmark pauses token-threshold capture, asks the user for the verified
+limit, and keeps manual and periodic snapshots active. It never guesses a context limit. The
+mapping follows Anthropic's
+[context-window documentation](https://platform.claude.com/docs/en/build-with-claude/context-windows).
+Override either value when needed:
 
-Sessions that compact frequently get protected more aggressively. Sessions that never compact barely notice Bookmark is there.
+```bash
+bookmark config --token-threshold 75
+bookmark config --context-limit 500000
+```
 
-## Time-Based Snapshots
+## Hooks
 
-Default: every **20 minutes** of active session time. Configurable:
+Bookmark installs four hooks because each protects a separate lifecycle boundary:
 
-```bash
-bookmark config --interval 10   # Every 10 minutes
-bookmark config --interval 30   # Every 30 minutes
-```
+| Hook | Needed for |
+|------|------------|
+| `SessionStart` | Restore the latest durable handoff into a new session |
+| `UserPromptSubmit` | Run periodic capture and model-aware token-threshold checks |
+| `PreCompact` | Save a final mechanical checkpoint before compaction |
+| `Stop` | Save at exit and require a complete semantic handoff once |
 
-Or set via environment: `BOOKMARK_INTERVAL=15`
+`UserPromptSubmit` is the only hook required for periodic and token-threshold capture. The other
+three complete the restore, pre-compaction, and exit continuity path.
 
-## Smart Mode (Optional)
+Manual capture does not require another hook: run `/bookmark:snapshot` or `bookmark snapshot`.
 
-For higher-quality extraction, pass `--smart` to use Claude Haiku (~$0.001 per snapshot):
+## Time-Based Snapshots
+
+Default: every **5 minutes** of active session time. Configurable:
 
 ```bash
-bookmark config --smart-default   # Enable by default
+bookmark config --interval 10   # Every 10 minutes
+bookmark config --interval 30   # Every 30 minutes
 ```
 
-Requires `ANTHROPIC_API_KEY`. Falls back to pattern matching if unavailable.
+Or set via environment: `BOOKMARK_INTERVAL=15`
 
 ## Storage
 
-All data lives in your project at `.claude/bookmarks/`:
+All data lives in your project at `.bookmark/`:
 
 ```
-.claude/bookmarks/
+.bookmark/
 ├── LATEST.md       # Hot context — what gets restored on SessionStart
 ├── index.json      # Snapshot index with stats
 ├── state.json      # Plugin state (compaction count, thresholds, timing)
@@ -146,13 +171,69 @@ All data lives in your project at `.claude/bookmarks/`:
 
 Automatically added to `.gitignore` — snapshot data never gets committed.
 
-## Zero Context Tax
+## Identity Block (v0.4+)
+
+Every `bookmark.context.md` should start with an `BOOKMARK_IDENTITY` HTML comment that
+declares which project and git state the summary belongs to. This makes cross-session
+restoration unambiguous — a bookmark can't be mistaken for a different repo's context.
 
-This is the key design principle. Every other approach to "memory" for Claude Code injects tokens into your context window, reducing the space available for actual work.
+```markdown
+# Session Context — Travel Planner
+
+<!-- BOOKMARK_IDENTITY
+scope: repo
+project: travel-planner
+repo_path: /Users/me/dev/git-folder/Travel Planner
+branch: feature/summer-camps
+head: 4988383
+written: 2026-04-11
+-->
+
+## Current Task
+...
+```
 
-Bookmark runs as an external CLI process. The hooks invoke `npx @tyroneross/bookmark` — a separate Node process that reads the transcript file directly, extracts patterns, and writes snapshot files. The only context injection is ~500-800 tokens on SessionStart to restore prior session context.
+Supported fields: `scope` (`repo` or `home`), `project`, `repo_path`, `repo_name`, `branch`,
+`head`, `base`, `written`, `written_by`. Unknown keys are preserved for forward compatibility.
 
-All the heavy lifting happens outside the context window.
+### Path validation
+
+At restore time, bookmark compares the identity's `repo_path` to the CWD it was invoked in.
+Mismatch → the restored content is prefixed with an "identity mismatch" warning, so the new
+session can verify the bookmark belongs to the project before acting on it.
+
+### Home-scope pointers
+
+A `scope: home` bookmark at `~/.bookmark/bookmark.context.md` is a **pointer**, not a
+session context. It contains `points_to_canonical` naming the real repo-scoped file:
+
+```markdown
+<!-- BOOKMARK_IDENTITY
+scope: home
+project: POINTER_ONLY
+points_to_project: travel-planner
+points_to_canonical: /Users/me/dev/git-folder/Travel Planner/.bookmark/bookmark.context.md
+-->
+```
+
+SessionStart automatically follows the pointer — a session launched from `~/` now gets
+routed to the canonical project bookmark without manual `cd`. Previously, the home
+bookmark would be served as if it were the active context (with potentially stale or
+wrong-project content).
+
+## Hard Staleness Block (v0.4+)
+
+Stale auto-restore is worse than no auto-restore: a 14-day-old bookmark prefixed with a
+soft warning still creates "confident wrong starts" because the warning reads as noise.
+Bookmark now **hard-blocks** auto-restore at **72 hours** — past that threshold, the
+restored content is replaced with a message telling you to pick a specific snapshot via
+`/bookmark:list` or read the file manually if you actually want it. Soft warnings still
+apply between 24h and 72h.
+
+## Small Context Footprint
+
+Bookmark performs mechanical capture outside the model context. It injects only the compact
+handoff on SessionStart and one short instruction when a token threshold is crossed.
 
 ## Configuration
 
@@ -160,11 +241,10 @@ All the heavy lifting happens outside the context window.
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `BOOKMARK_INTERVAL` | `20` | Snapshot interval in minutes |
-| `BOOKMARK_THRESHOLD` | `0.2,0.3,0.4,0.5,0.6` | Adaptive threshold levels |
-| `BOOKMARK_CONTEXT_LIMIT` | `200000` | Context window size in tokens |
-| `BOOKMARK_SMART` | `false` | Enable smart extraction by default |
-| `BOOKMARK_STORAGE_PATH` | `.claude/bookmarks` | Storage directory |
+| `BOOKMARK_INTERVAL` | `5` | Snapshot interval in minutes |
+| `BOOKMARK_TOKEN_THRESHOLD` | `0.75` | Context-used fraction that captures and alerts |
+| `BOOKMARK_CONTEXT_LIMIT` | model-aware | Explicit context-window override in tokens |
+| `BOOKMARK_STORAGE_PATH` | `.bookmark` | Storage directory |
 | `BOOKMARK_VERBOSE` | `false` | Enable verbose logging |
 | `BOOKMARK_SKIP_SETUP` | `false` | Skip postinstall auto-setup |
 
@@ -175,4 +255,17 @@ All the heavy lifting happens outside the context window.
 
 ## License
 
-MIT
+Apache-2.0
+
+## Codex
+
+This package now ships an additive Codex plugin surface alongside the existing Claude Code package. The Claude package remains authoritative for Claude behavior; the Codex package adds a parallel `.codex-plugin/plugin.json` install surface without changing the Claude runtime.
+
+Package root for Codex installs:
+- the repository root (`.`)
+
+Primary Codex surface:
+- skills from `./skills` when present
+- MCP config from `./.mcp.json` when present
+
+Install the package from this package root using your current Codex plugin install flow. The Codex package is additive only: Claude-specific hooks, slash commands, and agent wiring remain unchanged for Claude Code.

package/agents/snapshot-analyst.md

@@ -18,7 +18,7 @@ You analyze context snapshots to help users understand session history.
 
 ## Data Location
 
-All bookmark data is in `.claude/bookmarks/`:
+All bookmark data is in `.bookmark/`:
 - `LATEST.md` — Latest compressed summary
 - `index.json` — Snapshot index with stats
 - `state.json` — Plugin state (compaction count, thresholds)

package/commands/bookmark.md

@@ -0,0 +1,29 @@
+---
+description: "Show current session context and bookmark status"
+allowed-tools: Bash, Read
+---
+
+Show the current bookmark state for this project.
+
+{{#if ARGUMENTS}}
+Pass arguments to the bookmark CLI:
+
+```bash
+npx @tyroneross/bookmark {{ARGUMENTS}}
+```
+{{else}}
+Run status and show current context:
+
+```bash
+npx @tyroneross/bookmark status
+```
+
+Then check if `.bookmark/bookmark.context.md` exists in the current project and read it to show the user their last session context.
+
+Present:
+- Snapshot count and last snapshot time
+- Current session context summary (from bookmark.context.md) if it exists
+- Available commands: `/bookmark:snapshot`, `/bookmark:status`, `/bookmark:list`, `/bookmark:restore`
+{{/if}}
+
+*bookmark — session continuity*

package/commands/feedback.md

@@ -0,0 +1,37 @@
+---
+name: feedback
+description: Report a bug or send feedback about the bookmark plugin
+---
+
+# Report bookmark feedback
+
+File the user's report as a GitHub issue on `tyroneross/bookmark`. Issues are this plugin's
+support channel — the manifest carries no contact address by design.
+
+## Steps
+
+1. Ask what went wrong, if the user has not already said. One question, not a form.
+2. Gather the context that makes a report actionable, without interrogating the user:
+   - plugin version from `.claude-plugin/plugin.json`
+   - `claude --version`
+   - `uname -sm`
+   - which command or skill misbehaved, and what it did instead
+3. Show the user the exact title and body you intend to file. Their report, their words.
+4. Create it:
+
+```bash
+gh issue create --repo tyroneross/bookmark \
+  --title "<one line: what broke>" \
+  --body "<what happened / what was expected / steps / versions>"
+```
+
+5. If `gh` is missing or unauthenticated, do not fail — print the URL so the user
+   can open it in a browser: https://github.com/tyroneross/bookmark/issues/new
+
+6. Report the resulting issue URL back to the user.
+
+## Rules
+
+- A GitHub issue is public. Redact secrets, tokens, absolute home paths, and any
+  file contents the user has not seen before sending.
+- Never file without showing the user the body first.

package/commands/restore.md

@@ -5,25 +5,35 @@ argument-hint: "[SNAP_ID]"
 ---
 
 {{#if ARGUMENTS}}
-Load and display the full context from a specific snapshot:
+Load and display the full context from a specific snapshot. If the ID lives in a
+different project, `show` will resolve it via the global registry.
 
 ```bash
 npx @tyroneross/bookmark show {{ARGUMENTS}}
 ```
 
-Read the snapshot and present the decisions, status, open items, and unknowns to the user. Use this context to continue the work.
+Read the snapshot and present the decisions, status, open items, and unknowns to the user.
 
 {{else}}
-Show the latest snapshot and list available alternatives:
+Restore the most relevant context, using the same resolution chain as session startup
+(current project → home-scope pointer → last-active project via registry):
 
 ```bash
-npx @tyroneross/bookmark show --latest
+npx @tyroneross/bookmark restore --session-source clear
 ```
 
+If you want to pick a different snapshot, list recent ones:
+
 ```bash
 npx @tyroneross/bookmark list --limit 5
 ```
 
+Or view snapshots across all projects:
+
+```bash
+npx @tyroneross/bookmark list --all --limit 10
+```
+
 Present the restored context and ask the user which open item to continue with.
 {{/if}}
 

package/commands/snapshot.md

@@ -1,10 +1,9 @@
 ---
-description: "Take a manual context snapshot"
-allowed-tools: Bash
-argument-hint: "[--smart]"
+description: "Take a manual context snapshot and write session summary"
+allowed-tools: Bash, Write
 ---
 
-Take a manual context snapshot of the current session.
+Take a manual context snapshot. This captures file changes and tool usage from the current session transcript.
 
 {{#if ARGUMENTS}}
 ```bash
@@ -18,9 +17,22 @@ npx @tyroneross/bookmark snapshot --trigger manual
 
 After the snapshot is taken, confirm to the user with:
 - The snapshot ID
-- Number of decisions captured
 - Number of files tracked
-- Number of open items
-- Context remaining percentage
+- Number of tools tracked
+
+Then write the semantic handoff to the absolute path for `.bookmark/bookmark.context.md`.
+Start with `BOOKMARK_IDENTITY` and include these sections:
+
+- `## Current task`
+- `## Status`
+- `## Remaining work`
+- `## Decisions`
+- `## Risks and open questions`
+- `## Sources of truth`
+- `## Next steps`
+
+Separate completed, validated, committed, pushed, and deployed status. Use absolute paths in
+Sources of truth and Next steps. Point to durable files instead of copying long content, state
+unknowns explicitly, and keep the handoff under 800 tokens.
 
 *bookmark — context snapshot*

package/commands/status.md

@@ -13,7 +13,7 @@ Display the results including:
 - Number of snapshots
 - Compaction cycle count
 - Last snapshot time
-- Current adaptive threshold
+- Current token threshold, measured usage, and active model when available
 - Time until next scheduled snapshot
 
 *bookmark — context snapshot*