lorem-dev · May 22, 2026 · May 20, 2026 · May 22, 2026 · May 22, 2026 · May 22, 2026
diff --git a/CHANGES.md b/CHANGES.md
@@ -9,6 +9,30 @@
   per session; if the retry also fails, the error is forwarded to the
   AI client unchanged. Detection looks only at structural fields - no
   keyword matching against `result.content[].text`.
+- Per-agent installer logic moved into `internal/initflow/agents/<name>/`
+  subpackages (claude, codex, gemini, opencode, generic), each with
+  embedded templates. `AgentWriter` in `agents.go` is now a thin switch
+  dispatcher. Gemini CLI is now detected by `DetectAgents` and dispatched
+  to the new `gemini` subpackage (previously dead code). The dead
+  `agents_md.md.tmpl` template was removed.
+- `locksmith init` now adds `Bash(locksmith:*)` to
+  `permissions.allow` in `~/.claude/settings.json` so the agent can
+  call `locksmith` directly without per-call approval. Idempotent.
+- Agent instruction templates (Claude/Codex/Gemini/OpenCode and the
+  generic agent file) are now wrapped with `<!-- LOCKSMITH_START -->`
+  / `<!-- LOCKSMITH_END -->` markers so the locksmith-managed block
+  can be located and updated reliably.
+- `locksmith restart` command added: stops the running daemon and
+  starts a fresh one. Flags `--timeout` and `--no-start`. Use after a
+  binary upgrade or plugin re-extract; see `docs/restart.md`.
+- `locksmith init` appends an idempotent PATH-augmentation block to
+  the user's shell rc (`~/.zshrc` / `~/.bashrc` /
+  `~/.config/fish/config.fish`) when the locksmith binary directory
+  is not already on `$PATH`. Skipped silently when the directory is
+  already on PATH or when the rc file does not exist (init never
+  creates new rc files).
+- Add `vaults.<name>.vault` config field, delivered to plugins as `opts["vault"]`; used by the 1Password plugin to qualify non-`op://` paths.
+- Add 1Password vault plugin backed by the op CLI, auto-detected when `op` is installed.
 - docs(cli): drop Touch ID wording from CLI help, README, configuration
   and architecture docs, and plugin READMEs; keychain authorization is
   described as OS-delegated without naming a specific auth method
@@ -17,6 +41,28 @@
   external AI agent tooling (CodeGraph MCP server, obra/superpowers
   skill pack) are listed there instead. The `check-licenses` skill
   and `CONTRIBUTING.md` were updated to match.
+- Switch the Claude Code UserPromptSubmit hook from a shell script to
+  the native `locksmith session ensure --hook` invocation. The flag
+  produces a JSON env block via `encoding/json` (no `printf`, no
+  `$(...)`).
+- Auto-migrate existing installs: legacy `agent-hook.sh` references in
+  `~/.claude/settings.json` are rewritten in place on the next
+  `locksmith init`, the matching `Bash(.../agent-hook.sh)` permission
+  rule is dropped, and the on-disk script is removed.
+- `locksmith init` now automatically restarts a running daemon at the
+  end of its run so plugin/config changes take effect immediately.
+- `locksmith init` now installs a Codex `SessionStart` hook in
+  `~/.codex/hooks.json` when Codex is detected. The hook pre-warms
+  the locksmith daemon so vault unlock (passphrase, biometric) fires
+  before the agent's first secret request. Best-effort: any failure
+  is swallowed so Codex startup is never blocked. Codex prompts the
+  user to trust the hook on next run.
+- Agent instruction templates are now agent-specific: each template
+  describes only its own agent's session protocol (Claude relies on
+  the UserPromptSubmit hook; Codex / Gemini CLI / OpenCode / generic
+  use `export LOCKSMITH_SESSION=$(locksmith session ensure --quiet)`)
+  and includes usage examples for all three shipped vault types
+  (`gopass`, `keychain`, `1password`).
 
 ## Version v0.3.0 - 2026-05-15
 

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -2,6 +2,40 @@
 
 ## Repository: https://github.com/lorem-dev/locksmith
 
+<!-- CODEGRAPH_START -->
+## CodeGraph
+
+This project has a CodeGraph MCP server (`codegraph_*` tools) configured. CodeGraph is a tree-sitter-parsed knowledge graph of every symbol, edge, and file. Reads are sub-millisecond and return structural information grep cannot.
+
+### When to prefer codegraph over native search
+
+Use codegraph for **structural** questions — what calls what, what would break, where is X defined, what is X's signature. Use native grep/read only for **literal text** queries (string contents, comments, log messages) or after you already have a specific file open.
+
+| Question | Tool |
+|---|---|
+| "Where is X defined?" / "Find symbol named X" | `codegraph_search` |
+| "What calls function Y?" | `codegraph_callers` |
+| "What does Y call?" | `codegraph_callees` |
+| "What would break if I changed Z?" | `codegraph_impact` |
+| "Show me Y's signature / source / docstring" | `codegraph_node` |
+| "Give me focused context for a task/area" | `codegraph_context` |
+| "Survey an unfamiliar module/topic" | `codegraph_explore` |
+| "What files exist under path/" | `codegraph_files` |
+| "Is the index healthy?" | `codegraph_status` |
+
+### Rules of thumb
+
+- **Trust codegraph results.** They come from a full AST parse. Do NOT re-verify them with grep — that's slower, less accurate, and wastes context.
+- **Don't grep first** when looking up a symbol by name. `codegraph_search` is faster and returns kind + location + signature in one call.
+- **Don't chain `codegraph_search` + `codegraph_node`** when you just want context — `codegraph_context` is one call.
+- **`codegraph_explore` is the heavy hitter** for unfamiliar areas — it returns full source from all relevant files in one call, but is token-heavy. If your harness supports parallel subagents (e.g., Claude Code's Task tool), spawn one for explore-class questions to keep main session context clean.
+- **Index lag**: the file watcher debounces ~500ms behind writes; don't re-query immediately after editing a file in the same turn.
+
+### If `.codegraph/` doesn't exist
+
+The MCP server returns "not initialized." Ask the user: *"I notice this project doesn't have CodeGraph initialized. Want me to run `codegraph init -i` to build the index?"*
+<!-- CODEGRAPH_END -->
+
 ## Language
 All code, comments, commit messages, and documentation must be in English.
 When conversing with the user, always respond in the user's language.
@@ -11,6 +45,7 @@ When conversing with the user, always respond in the user's language.
 - SDK: `github.com/lorem-dev/locksmith/sdk`
 - Gopass plugin: `github.com/lorem-dev/locksmith-plugin-gopass`
 - Keychain plugin: `github.com/lorem-dev/locksmith-plugin-keychain`
+- 1Password plugin: `github.com/lorem-dev/locksmith-plugin-1password`
 
 ## Project Structure
 - `cmd/locksmith/` - CLI + daemon entry point
@@ -171,6 +206,38 @@ than duplicating it.
 Whenever a plugin's behavior, configuration fields, or external requirements
 change, update `plugins/<name>/README.md` in the same commit.
 
+## Adding a new vault plugin
+
+When you add a new vault plugin under `plugins/<name>/`, update the
+following in the same change:
+
+1. `internal/config/types.go` - add a `Vault<Name>` constant.
+2. `internal/initflow/detect.go` - add detection of the vault binary
+   and flip `Implemented: true` once the plugin is shipped.
+3. `docs/configuration.md` - new section describing the vault type
+   and its options.
+4. `docs/plugins/README.md` - add to the bundled-plugins list.
+5. `README.md` - update the vault-comparison table and the
+   Configuration example.
+6. `PLUGINS.md` - add to the opening paragraph.
+7. `CHANGES.md` - bullet under `## Development`.
+8. **Agent templates** - update every template under
+   `internal/initflow/agents/<agent>/templates/` to add a usage
+   example in the "Retrieving Secrets" section:
+
+       locksmith get --vault <type> --path "<example-path>"
+
+   Templates touched: `agents/claude/templates/claude_md.md.tmpl`,
+   `agents/claude/templates/claude_skill.md.tmpl`,
+   `agents/codex/templates/codex_agents.md.tmpl`,
+   `agents/gemini/templates/gemini_md.md.tmpl`,
+   `agents/opencode/templates/instructions.md.tmpl`, and
+   `agents/generic/templates/instructions.md.tmpl`.
+
+9. Run `make verify` to ensure all gates pass. The cross-template
+   tests in `internal/initflow/agents_test.go` block regressions by
+   asserting that every shipped vault appears in every template.
+
 ## Bundled Plugins
 
 Default plugins (`gopass`, `keychain`) and `locksmith-pinentry` ship

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -249,7 +249,7 @@ Relates #<issue>
 
 ```
 feat(session): add TTL-based expiry with memory wipe
-fix(keychain): handle errSecUserCanceled from Touch ID prompt
+fix(keychain): handle errSecUserCanceled from Keychain prompt
 chore: update golangci-lint to v1.57
 ```
 
@@ -270,8 +270,8 @@ docs completeness, and CHANGES.md checks - run it before submitting.
 
 ## Plugin versioning and compatibility
 
-Bundled plugins (`plugins/gopass`, `plugins/keychain`) and any
-third-party plugins follow the rules below. `make test-race`
+Bundled plugins (`plugins/gopass`, `plugins/keychain`, `plugins/onepassword`)
+and any third-party plugins follow the rules below. `make test-race`
 enforces them - a plugin PR cannot land green without satisfying
 every check.
 

diff --git a/PLUGINS.md b/PLUGINS.md
@@ -1,8 +1,9 @@
 # Locksmith Plugins
 
-Locksmith ships with built-in vault plugins (`gopass`, `keychain`) and
-`locksmith-pinentry` embedded inside the `locksmith` binary as a per-platform
-zip. One `go install` is enough - no separate plugin install step.
+Locksmith ships with built-in vault plugins (`gopass`, `keychain`,
+`1password`) and `locksmith-pinentry` embedded inside the `locksmith`
+binary as a per-platform zip. One `go install` is enough - no separate
+plugin install step.
 
 ## Lockstep versioning
 
@@ -67,3 +68,5 @@ version compatible with your `locksmith`. See
   plugin guide.
 - [plugins/keychain/README.md](plugins/keychain/README.md) - built-in
   keychain plugin guide.
+- [plugins/onepassword/README.md](plugins/onepassword/README.md) -
+  built-in 1Password plugin guide.
diff --git a/README.md b/README.md
@@ -1,8 +1,8 @@
 # Locksmith
 
 Secure middleware that gives AI agents access to secrets stored in vault providers
-(macOS Keychain, gopass), with per-session caching and
-vault-delegated authorization (Keychain, GPG passphrase).
+(macOS Keychain, gopass, 1Password), with per-session caching and
+vault-delegated authorization (Keychain, GPG passphrase, 1Password desktop app).
 
 ## Installation
 
@@ -39,16 +39,16 @@ locksmith init
 ```
 
 `locksmith init` is an interactive wizard: it detects your available vaults
-(Keychain, gopass), writes a starter config, and installs hooks for the AI
-agents you use (Claude Code, Cursor, Copilot, Codex, Gemini CLI) so they get
+(Keychain, gopass, 1Password), writes a starter config, and installs hooks for the AI
+agents you use (Claude Code, Codex, Gemini CLI, OpenCode) so they get
 a `LOCKSMITH_SESSION` automatically. The daemon is started by the installed
 shell hook on the next shell session.
 
 ## Configuration
 
 After `init`, your config lives at `~/.config/locksmith/config.yaml`. A
-minimal example with two vaults (gopass for work, macOS Keychain for
-personal) and three named keys:
+minimal example with three vaults (gopass for work, macOS Keychain for
+personal, 1Password for shared team secrets) and four named keys:
 
 ```yaml
 defaults:
@@ -61,6 +61,9 @@ vaults:
   personal:
     type: keychain
     service: locksmith    # macOS only; Keychain service name
+  op:
+    type: 1password
+    vault: Personal       # default 1Password vault for non-qualified paths
 
 keys:
   github-token:
@@ -72,6 +75,9 @@ keys:
   slack-webhook:
     vault: personal
     path: slack-incoming-webhook
+  notion-token:
+    vault: op
+    path: Notion          # resolves to op://Personal/Notion/password
 
 mcp:
   servers:
@@ -197,19 +203,22 @@ HTTP) instead, which has no long-lived GET.
 
 See the [Configuration Reference](docs/configuration.md#mcp-servers) for
 configuring named servers in `config.yaml`. For client-specific notes
-(Claude Code, Cursor, Copilot, Codex, Gemini CLI), see
+(Claude Code, Codex, Gemini CLI, OpenCode), see
 [Agent Integration](docs/agent-integration.md).
 
 ## Agent Usage
 
 Locksmith provides a session-aware CLI for AI agents. See
 [Agent Integration](docs/agent-integration.md) for the full protocol and
-platform-specific setup (Claude Code hooks, Gemini CLI, Cursor, Copilot,
-Codex).
+platform-specific setup (Claude Code hooks, Codex hook, Gemini CLI,
+OpenCode).
 
 For Claude Code, run `locksmith init` - the `UserPromptSubmit` hook is
-installed automatically and injects `LOCKSMITH_SESSION` before each prompt.
-Restart Claude Code after running `init`.
+installed automatically. The hook command is `locksmith session ensure
+--hook` (a native invocation - no shell script), and `init` also adds
+`Bash(locksmith:*)` to `permissions.allow`, augments your shell PATH
+if needed, and restarts any running daemon. Restart Claude Code after
+running `init`.
 
 **Quick start:**
 
@@ -236,17 +245,18 @@ in `~/.config/locksmith/config.yaml` (default: `true`).
 |-------|----------|------|--------|
 | macOS Keychain | macOS | Keychain | Supported |
 | gopass | macOS, Linux | GPG passphrase | Supported |
-| 1Password | macOS, Linux | Keychain / master password | Planned |
+| 1Password | macOS, Linux | Desktop app (biometric) / `op signin` | Supported |
 | GNOME Keyring | Linux | Keyring password | Planned |
 
 ### Plugin Setup Guides
 
 Per-plugin installation, configuration examples, and troubleshooting:
 
-| Plugin   | Platform     | Setup guide                                              |
-|----------|--------------|----------------------------------------------------------|
-| gopass   | Linux, macOS | [`plugins/gopass/README.md`](plugins/gopass/README.md)   |
-| keychain | macOS only   | [`plugins/keychain/README.md`](plugins/keychain/README.md) |
+| Plugin      | Platform     | Setup guide                                                          |
+|-------------|--------------|----------------------------------------------------------------------|
+| gopass      | Linux, macOS | [`plugins/gopass/README.md`](plugins/gopass/README.md)               |
+| keychain    | macOS only   | [`plugins/keychain/README.md`](plugins/keychain/README.md)           |
+| 1password   | Linux, macOS | [`plugins/onepassword/README.md`](plugins/onepassword/README.md)     |
 
 ## Documentation