agentdir-cli 0.7.5__tar.gz → 0.7.7__tar.gz

{agentdir_cli-0.7.5/src/agentdir_cli.egg-info → agentdir_cli-0.7.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentdir-cli
-Version: 0.7.5
+Version: 0.7.7
 Summary: Local-first Maildir-inspired work mailstore for software agents
 Author: AgentDir Contributors
 License-Expression: MIT
@@ -34,7 +34,7 @@ Dynamic: license-file
 # AgentDir
 
 <p align="center">
-  <img src="docs/assets/agentdir-overview.png" alt="AgentDir turns agent work into a saved trail, searchable memory, and proof for engineers." />
+  <img src="https://raw.githubusercontent.com/jstxn/agentdir/main/docs/assets/agentdir-overview.png" alt="AgentDir turns agent work into a saved trail, searchable memory, and proof for engineers." />
 </p>
 
 <p align="center">
@@ -137,6 +137,16 @@ agentdir --version
 agentdir --help
 ```
 
+Update an existing install to the latest release and refresh adoption for the
+current repository:
+
+```bash
+agentdir update
+agentdir update --dry-run
+```
+
+The older `agentdir --upgrade` interface remains supported for compatibility.
+
 ## Pi Package
 
 Pi users can install this repository as a Pi package so the AgentDir skill is
@@ -145,7 +155,7 @@ available automatically during coding tasks:
 Package page: [@jstxn/agentdir-pi](https://pi.dev/packages/@jstxn/agentdir-pi)
 
 ```bash
-pi install npm:@jstxn/agentdir-pi@0.7.5
+pi install npm:@jstxn/agentdir-pi@0.7.7
 # or install directly from a local checkout / release tag:
 pi install /absolute/path/to/agentdir
 pi install git:github.com/jstxn/agentdir@<tag-or-commit>
@@ -191,6 +201,16 @@ instead of project instruction files:
 agentdir adopt --install-skill store --install-generic store --integration-target store
 ```
 
+Adoption adapts to repos where other tools own these files. When
+[rulesync](https://github.com/dyoshikawa/rulesync) generates the guidance
+files, the managed rule is written to `.rulesync/rules/agentdir.md` instead so
+it survives regeneration, and files with generated-file headers are never
+edited without `--force`. When lefthook, husky, or pre-commit own the Git
+hooks, adopt warns up front, `agentdir doctor` flags hook shims those tools
+later overwrite, and `agentdir hooks install` restores them. See
+[docs/INSTALL.md](docs/INSTALL.md#coexisting-with-rule-generators-and-hook-managers)
+for details.
+
 For non-interactive installs, choose the ignore destination explicitly:
 
 ```bash
@@ -212,17 +232,22 @@ Default adoption writes only local files:
 
 ```text
 <repo>/.agentdir/                         # evidence, artifacts, indexes, state
-<repo>/.git/hooks/*                       # managed hook shims with backups
+<repo>/.agentdir/hooks.json               # installed-hook drift manifest
+<active-hooks-directory>/*                # managed hook shims with backups
 <repo>/AGENTS.md                          # generic / Codex-readable guidance
 <repo>/CLAUDE.md                          # Claude Code guidance
 <repo>/.github/copilot-instructions.md    # Copilot guidance
 <repo>/.cursor/rules/agentdir.mdc         # Cursor guidance
 <repo>/.windsurf/rules/agentdir.md        # Windsurf guidance
+<repo>/.rulesync/rules/agentdir.md        # rulesync source, when detected
 ~/.codex/skills/agentdir/SKILL.md         # Codex skill, by default
 ```
 
 Managed guidance is wrapped in AgentDir markers. Existing unmanaged content is
-preserved where the target format supports managed blocks.
+preserved where the target format supports managed blocks. The active hooks
+directory is `.git/hooks` by default and follows `core.hooksPath` or linked
+worktree configuration. In rulesync repos, the source rule replaces the listed
+project guidance files as the managed source of truth.
 
 ## Inspect A Session
 

{agentdir_cli-0.7.5 → agentdir_cli-0.7.7}/README.md

@@ -1,7 +1,7 @@
 # AgentDir
 
 <p align="center">
-  <img src="docs/assets/agentdir-overview.png" alt="AgentDir turns agent work into a saved trail, searchable memory, and proof for engineers." />
+  <img src="https://raw.githubusercontent.com/jstxn/agentdir/main/docs/assets/agentdir-overview.png" alt="AgentDir turns agent work into a saved trail, searchable memory, and proof for engineers." />
 </p>
 
 <p align="center">
@@ -104,6 +104,16 @@ agentdir --version
 agentdir --help
 ```
 
+Update an existing install to the latest release and refresh adoption for the
+current repository:
+
+```bash
+agentdir update
+agentdir update --dry-run
+```
+
+The older `agentdir --upgrade` interface remains supported for compatibility.
+
 ## Pi Package
 
 Pi users can install this repository as a Pi package so the AgentDir skill is
@@ -112,7 +122,7 @@ available automatically during coding tasks:
 Package page: [@jstxn/agentdir-pi](https://pi.dev/packages/@jstxn/agentdir-pi)
 
 ```bash
-pi install npm:@jstxn/agentdir-pi@0.7.5
+pi install npm:@jstxn/agentdir-pi@0.7.7
 # or install directly from a local checkout / release tag:
 pi install /absolute/path/to/agentdir
 pi install git:github.com/jstxn/agentdir@<tag-or-commit>
@@ -158,6 +168,16 @@ instead of project instruction files:
 agentdir adopt --install-skill store --install-generic store --integration-target store
 ```
 
+Adoption adapts to repos where other tools own these files. When
+[rulesync](https://github.com/dyoshikawa/rulesync) generates the guidance
+files, the managed rule is written to `.rulesync/rules/agentdir.md` instead so
+it survives regeneration, and files with generated-file headers are never
+edited without `--force`. When lefthook, husky, or pre-commit own the Git
+hooks, adopt warns up front, `agentdir doctor` flags hook shims those tools
+later overwrite, and `agentdir hooks install` restores them. See
+[docs/INSTALL.md](docs/INSTALL.md#coexisting-with-rule-generators-and-hook-managers)
+for details.
+
 For non-interactive installs, choose the ignore destination explicitly:
 
 ```bash
@@ -179,17 +199,22 @@ Default adoption writes only local files:
 
 ```text
 <repo>/.agentdir/                         # evidence, artifacts, indexes, state
-<repo>/.git/hooks/*                       # managed hook shims with backups
+<repo>/.agentdir/hooks.json               # installed-hook drift manifest
+<active-hooks-directory>/*                # managed hook shims with backups
 <repo>/AGENTS.md                          # generic / Codex-readable guidance
 <repo>/CLAUDE.md                          # Claude Code guidance
 <repo>/.github/copilot-instructions.md    # Copilot guidance
 <repo>/.cursor/rules/agentdir.mdc         # Cursor guidance
 <repo>/.windsurf/rules/agentdir.md        # Windsurf guidance
+<repo>/.rulesync/rules/agentdir.md        # rulesync source, when detected
 ~/.codex/skills/agentdir/SKILL.md         # Codex skill, by default
 ```
 
 Managed guidance is wrapped in AgentDir markers. Existing unmanaged content is
-preserved where the target format supports managed blocks.
+preserved where the target format supports managed blocks. The active hooks
+directory is `.git/hooks` by default and follows `core.hooksPath` or linked
+worktree configuration. In rulesync repos, the source rule replaces the listed
+project guidance files as the managed source of truth.
 
 ## Inspect A Session
 

{agentdir_cli-0.7.5 → agentdir_cli-0.7.7}/docs/AGENTIC_CODING.md

@@ -87,7 +87,7 @@ agentdir memory backend list
 agentdir memory daemon status
 ```
 
-`agentdir memory search` rebuilds the index by default, then ranks matching envelopes and derived session summaries by vector similarity. `agentdir memory explain` shows why a hit matched. `agentdir context build` combines memory, current-session evidence, and recent session summaries into an agent-ready context pack. The raw Maildir envelopes remain the source of truth, so the memory layer can always be deleted and rebuilt.
+`agentdir memory search` incrementally updates the index by default (new and deleted envelopes only; pass `--no-rebuild` to skip even that), then ranks matching envelopes and derived session summaries by vector similarity. `agentdir memory explain` shows why a hit matched. `agentdir context build` combines memory, current-session evidence, and recent session summaries into an agent-ready context pack. The raw Maildir envelopes remain the source of truth, so the memory layer can always be deleted and rebuilt.
 
 When retrieved context materially influences a plan, tool call, answer, or handoff,
 emit an auditable context pack:
@@ -157,6 +157,12 @@ agentdir run -- git diff --check
 
 `agentdir run` streams command output to the terminal and records both the call and the result. Stored output is truncated at a bounded size and common secret-like patterns are redacted in the stored envelope. AgentDir also redacts common secret-like patterns from emitted message bodies before persistence. Agents should use this automatically for commands they run as evidence.
 
+When captured output is truncated, `agentdir run` prints a warning to stderr and the stored `tool.result` carries an `X-AgentDir-Truncated` header. Downstream surfaces treat the evidence as partial: `evidence` marks the row `truncated=true`, `audit session` reports a `truncated_evidence` warning, and `audit claims` downgrades claims resting on truncated successful evidence from `supported` to `partial` (which fails `--strict`). Raise the limit with `--max-capture-bytes` when full output matters for a claim.
+
+`agentdir run` supports `--timeout <seconds>` (kills the command and records exit 124), `--session require|create|auto|<id>` to control session placement, and `--json` for a machine-readable run summary after the streamed output.
+
+Exit codes are structured for agents: 2 = user error, 3 = state error (no root or no active session — the error message names the recovery command), 4 = missing dependency, 5 = configuration error. With `--json`, failures also print `{"success": false, "exit_code": ..., "error": ..., "error_code": ...}` to stdout. Every command accepts `--quiet` for exit-code-only checks.
+
 Do not wrap routine exploration commands such as `rg`, `sed`, `nl`, `cat`, `ls`, `find`, or quick read-only `git status` checks. Use plain shell commands while reading files, mapping code, or gathering low-level context. The evidence trail should capture verification, reproduced failures, important diagnostics, and final support for claims, not every glance at a file.
 
 ## Capturing Diffs As Artifacts

{agentdir_cli-0.7.5 → agentdir_cli-0.7.7}/docs/INSTALL.md

@@ -48,27 +48,30 @@ If `~/.local/bin` is not on PATH, add it:
 export PATH="$HOME/.local/bin:$PATH"
 ```
 
-## Upgrade Existing Installs
+## Update Existing Installs
 
 From any repo where AgentDir should stay adopted:
 
 ```bash
-agentdir --upgrade
+agentdir update
 ```
 
-The upgrade command resolves the latest GitHub Release, reinstalls AgentDir,
+The update command resolves the latest GitHub Release, reinstalls AgentDir,
 then re-runs adoption for the current git repository. It refreshes hooks, the
 Codex skill, and broad project guidance by default, then runs `doctor`.
 
 Useful variants:
 
 ```bash
-agentdir --upgrade --upgrade-install-skill none
-agentdir --upgrade --upgrade-no-adopt
-agentdir --upgrade --upgrade-version v0.7.5
-agentdir --upgrade --upgrade-dry-run
+agentdir update --install-skill none
+agentdir update --no-adopt
+agentdir update --version v0.7.7
+agentdir update --dry-run
 ```
 
+The older `agentdir --upgrade` interface and its `--upgrade-*` options remain
+supported for compatibility.
+
 ## Verify Install
 
 ```bash
@@ -96,13 +99,13 @@ agentdir work finish --json
 If you already have the wheel asset:
 
 ```bash
-AGENTDIR_WHEEL=/path/to/agentdir_cli-0.7.5-py3-none-any.whl bash scripts/install.sh
+AGENTDIR_WHEEL=/path/to/agentdir_cli-0.7.7-py3-none-any.whl bash scripts/install.sh
 ```
 
 To force the virtual environment installer even when `pipx` is present:
 
 ```bash
-AGENTDIR_FORCE_VENV=1 AGENTDIR_WHEEL=/path/to/agentdir_cli-0.7.5-py3-none-any.whl bash scripts/install.sh
+AGENTDIR_FORCE_VENV=1 AGENTDIR_WHEEL=/path/to/agentdir_cli-0.7.7-py3-none-any.whl bash scripts/install.sh
 ```
 
 ## Roll Back To The Previous Release
@@ -119,13 +122,13 @@ curl -fsSL https://raw.githubusercontent.com/jstxn/agentdir/main/scripts/rollbac
 To choose a specific release:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/jstxn/agentdir/main/scripts/rollback.sh | bash -s -- v0.7.4
+curl -fsSL https://raw.githubusercontent.com/jstxn/agentdir/main/scripts/rollback.sh | bash -s -- v0.7.6
 ```
 
 The equivalent manual rollback is:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/jstxn/agentdir/main/scripts/install.sh | AGENTDIR_VERSION=v0.7.4 bash
+curl -fsSL https://raw.githubusercontent.com/jstxn/agentdir/main/scripts/install.sh | AGENTDIR_VERSION=v0.7.6 bash
 ```
 
 ## Optional Extras
@@ -143,6 +146,34 @@ pipx inject agentdir-cli 'agentdir-cli[team]'
 `semantic` adds local embeddings and the embedded vector backend configuration
 surface. `team` adds optional shared-memory backend clients.
 
+### When The Semantic Extra Is Worth It
+
+The default retrieval backend (`local-hybrid`) combines lexical passage
+matching with lightweight hashed vectors. It needs no model download and is
+usually enough when memory queries reuse the project's own vocabulary: error
+strings, subsystem names, command names, file paths.
+
+Install the `semantic` extra and opt in when retrieval quality matters more
+than setup weight:
+
+```bash
+pipx inject agentdir-cli 'agentdir-cli[semantic]'
+agentdir memory embeddings configure fastembed   # one-time model download
+agentdir memory backend configure sqlite-vec     # optional: faster large stores
+```
+
+Reach for it when:
+
+- queries are paraphrases rather than the recorded wording ("auth timeouts"
+  should match "login requests hang for 30s"),
+- memory is federated across several repos with different vocabularies,
+- the store has grown past tens of thousands of passages and `sqlite-vec`
+  lookup speed starts to matter.
+
+Skip it for single-repo stores with recent, literally-worded memory - the
+default backend retrieves those well without the model download.
+`agentdir memory backend status` shows which backends are active.
+
 ## Store Location Scopes
 
 AgentDir stores mailboxes, artifacts, and indexes in an AgentDir root. You can choose the root explicitly or use a scope.
@@ -233,6 +264,71 @@ agentdir integrations install all --target project
 agentdir integrations doctor --json
 ```
 
+## Coexisting With Rule Generators And Hook Managers
+
+Some repos generate their agent guidance files and Git hooks from another
+source of truth. Adoption detects the common tools and adapts so managed
+content is not silently wiped.
+
+### Rule generators (rulesync)
+
+When a repo uses [rulesync](https://github.com/dyoshikawa/rulesync)
+(`.rulesync/` or `rulesync.jsonc` present), `CLAUDE.md`, `AGENTS.md`,
+`.cursor/rules/`, and friends are generated files: the next
+`rulesync generate` (often wired into `pnpm rulesync`) rewrites them and drops
+any managed block. `agentdir adopt` therefore writes the managed rule to the
+rulesync source instead:
+
+```text
+.rulesync/rules/agentdir.md   # root: false, targets: ["*"]
+```
+
+Run `rulesync generate` afterwards to propagate it into every generated tool
+file; it now survives regeneration. The skipped generated files are listed in
+the adopt output. To select the classic project-file destinations, use
+`agentdir adopt --install-integrations project-files`. Existing files with
+generated headers remain protected; add `--force` only when you intentionally
+want to edit those files directly.
+
+Independent of rulesync, adoption refuses to insert managed blocks into any
+existing file whose header marks it as generated (`DO NOT EDIT`,
+`@generated`, `generated by ...`) unless `--force` is given.
+
+### Git hook managers (lefthook, husky, pre-commit)
+
+AgentDir hook shims chain whatever hook they replace, so they coexist with a
+hook manager - until the manager reinstalls itself. `lefthook install` and
+`pre-commit install` rewrite `.git/hooks/*` (package installs typically
+trigger lefthook via a postinstall script), and husky points
+`core.hooksPath` at a directory it regenerates. Any of these silently stops
+AgentDir's git recording.
+
+Adoption now defends against that:
+
+- adopt and `agentdir hooks install` detect lefthook, husky, pre-commit, and a
+  configured `core.hooksPath`, and warn about the overwrite behavior up front;
+- installed shims are recorded in `.agentdir/hooks.json`, and `agentdir
+  doctor` (also run by `status`, `adopt`, and `work finish`) warns when a
+  recorded shim was overwritten or removed, naming the tool that did it;
+- rerunning `agentdir hooks install` restores the shims without `--force` when
+  the clobbering script came from a known hook manager, and chains the
+  manager's hook so both keep running;
+- shims are installed into the hooks directory git actually consults
+  (`core.hooksPath` and linked worktrees included).
+
+After a `pnpm install` or similar in a lefthook repo, either rerun
+`agentdir hooks install` or let the next doctor run flag it. If the churn is
+unwelcome, adopt with `--no-hooks` and rely on session recording without git
+hook events, or run the recorder from the hook manager itself, e.g. in
+`lefthook.yml`:
+
+```yaml
+post-commit:
+  jobs:
+    - name: agentdir-record
+      run: agentdir hooks record --hook post-commit --original-exit-code 0 || true
+```
+
 ## Install From Source
 
 For local development:

{agentdir_cli-0.7.5 → agentdir_cli-0.7.7}/docs/PI_PACKAGE.md

@@ -34,7 +34,7 @@ pi install git:github.com/jstxn/agentdir@<tag-or-commit>
 If the npm package has been published:
 
 ```bash
-pi install npm:@jstxn/agentdir-pi@0.7.5
+pi install npm:@jstxn/agentdir-pi@0.7.7
 ```
 
 Use `pi config` to enable or disable the bundled skill after installation.
@@ -48,7 +48,7 @@ The root `package.json` declares the Pi resources:
   "keywords": ["pi-package"],
   "pi": {
     "skills": ["./skills"],
-    "image": "https://raw.githubusercontent.com/jstxn/agentdir/v0.7.5/docs/assets/agentdir-overview.png"
+    "image": "https://raw.githubusercontent.com/jstxn/agentdir/v0.7.7/docs/assets/agentdir-overview.png"
   }
 }
 ```

{agentdir_cli-0.7.5 → agentdir_cli-0.7.7}/docs/RELEASING.md

@@ -31,9 +31,9 @@ chmod +x dist/rollback-agentdir.sh
 Expected assets (substitute the release version):
 
 ```text
-dist/agentdir_cli-0.7.5-py3-none-any.whl
-dist/agentdir_cli-0.7.5.tar.gz
-dist/jstxn-agentdir-pi-0.7.5.tgz
+dist/agentdir_cli-0.7.7-py3-none-any.whl
+dist/agentdir_cli-0.7.7.tar.gz
+dist/jstxn-agentdir-pi-0.7.7.tgz
 dist/install-agentdir.sh
 dist/rollback-agentdir.sh
 ```
@@ -41,19 +41,19 @@ dist/rollback-agentdir.sh
 ## Tag And Release
 
 ```bash
-git tag -a v0.7.5 -m "Release AgentDir v0.7.5"
+git tag -a v0.7.7 -m "Release AgentDir v0.7.7"
 git push origin main
-git push origin v0.7.5
+git push origin v0.7.7
 
-gh release create v0.7.5 \
-  dist/agentdir_cli-0.7.5-py3-none-any.whl \
-  dist/agentdir_cli-0.7.5.tar.gz \
-  dist/jstxn-agentdir-pi-0.7.5.tgz \
+gh release create v0.7.7 \
+  dist/agentdir_cli-0.7.7-py3-none-any.whl \
+  dist/agentdir_cli-0.7.7.tar.gz \
+  dist/jstxn-agentdir-pi-0.7.7.tgz \
   dist/install-agentdir.sh \
   dist/rollback-agentdir.sh \
   --repo jstxn/agentdir \
-  --title "AgentDir v0.7.5" \
-  --notes-file docs/releases/v0.7.5.md
+  --title "AgentDir v0.7.7" \
+  --notes-file docs/releases/v0.7.7.md
 ```
 
 Publishing the release triggers `publish.yml`, which rebuilds the sdist and
@@ -65,7 +65,7 @@ Use a disposable environment:
 
 ```bash
 tmp="$(mktemp -d)"
-gh release download v0.7.5 --repo jstxn/agentdir --pattern install-agentdir.sh --dir "$tmp"
+gh release download v0.7.7 --repo jstxn/agentdir --pattern install-agentdir.sh --dir "$tmp"
 AGENTDIR_PREFIX="$tmp/prefix" AGENTDIR_HOME="$tmp/home" bash "$tmp/install-agentdir.sh"
 "$tmp/prefix/bin/agentdir" --help
 "$tmp/prefix/bin/agentdir" --version
@@ -101,13 +101,13 @@ tmp="$(mktemp -d)"
 AGENTDIR_PREFIX="$tmp/prefix" \
 AGENTDIR_HOME="$tmp/home" \
 AGENTDIR_FORCE_VENV=1 \
-AGENTDIR_WHEEL="$PWD/dist/agentdir_cli-0.7.5-py3-none-any.whl" \
+AGENTDIR_WHEEL="$PWD/dist/agentdir_cli-0.7.7-py3-none-any.whl" \
   bash dist/install-agentdir.sh
 
 AGENTDIR_PREFIX="$tmp/prefix" \
 AGENTDIR_HOME="$tmp/home" \
 AGENTDIR_FORCE_VENV=1 \
-  bash dist/rollback-agentdir.sh v0.7.4
+  bash dist/rollback-agentdir.sh v0.7.6
 
 "$tmp/prefix/bin/agentdir" --help
 ```

{agentdir_cli-0.7.5 → agentdir_cli-0.7.7}/docs/TECH_BRIEF.md

@@ -411,7 +411,7 @@ agentdir session ensure [--id <id>] [--title <title>]
 agentdir session start [--id <id>] [--title <title>]
 agentdir session current
 agentdir session end [--summary <file-or-text>]
-agentdir run [--session <id>] [--name <tool>] -- <command> [args...]
+agentdir run [--session auto|require|create|<id>] [--name <tool>] [--timeout <seconds>] [--json] -- <command> [args...]
 agentdir emit [--root <root>] [--scope <scope>] [--session <id>] --type <type> --body <file>
 agentdir actor create [--root <root>] [--scope <scope>] <actor-id>
 agentdir send [--root <root>] [--scope <scope>] --from <actor> --to <actor> --type <type> --body <file>
@@ -487,6 +487,26 @@ The memory daemon is an opt-in warm indexer. It records process state under
 roots, and can use `watchfiles` when that extra is installed. Commands remain
 correct without the daemon because the index is still rebuildable on demand.
 
+## Exit Codes
+
+`agentdir` commands use a small exit-code taxonomy so agents can branch on
+failure class without parsing stderr:
+
+```text
+0  success
+1  command-specific failure result (doctor unhealthy, strict audit violations,
+   secrets found); agentdir run passes through the wrapped command's exit code,
+   with 124 reserved for --timeout kills
+2  user error: bad arguments or flags
+3  state error: not an AgentDir root, or no active session
+4  missing dependency: e.g. git repository required
+5  configuration error: unsupported store version, corrupted config
+```
+
+With `--json`, failures also print a structured error envelope to stdout:
+`{"success": false, "exit_code": <n>, "error": "...", "error_code": "<class>", "data": null}`.
+All commands accept `--quiet` to suppress stdout for exit-code-only checks.
+
 ## 14. Implementation Recommendation
 
 The current implementation uses Python.

agentdir_cli-0.7.7/docs/releases/v0.7.6.md

@@ -0,0 +1,39 @@
+# AgentDir v0.7.6
+
+AgentDir v0.7.6 fixes the project page rendering on PyPI.
+
+## Changes
+
+- Use an absolute URL for the README overview image. PyPI renders the README
+  as the `agentdir-cli` project description but does not resolve
+  repository-relative image paths, so the overview image rendered as a broken
+  icon on the project page.
+
+## Install
+
+From PyPI:
+
+```bash
+uv tool install agentdir-cli
+# or
+pipx install agentdir-cli
+```
+
+Or with the release installer:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/jstxn/agentdir/main/scripts/install.sh | bash
+```
+
+Install the Pi package from npm or the release tag:
+
+```bash
+pi install npm:@jstxn/agentdir-pi@0.7.6
+pi install git:github.com/jstxn/agentdir@v0.7.6
+```
+
+Rollback to v0.7.5 is one command:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/jstxn/agentdir/main/scripts/rollback.sh | bash
+```

agentdir_cli-0.7.7/docs/releases/v0.7.7.md

@@ -0,0 +1,57 @@
+# AgentDir v0.7.7
+
+AgentDir v0.7.7 makes self-updates easier to discover and keeps adoption
+reliable in repositories where other tools generate agent guidance or Git
+hooks.
+
+## Changes
+
+- Add `agentdir update` as the canonical self-update command. It uses the
+  existing upgrade implementation, supports `--version`, `--repo`,
+  `--install-skill`, `--no-adopt`, `--no-hooks`, `--dry-run`, and `--json`, and
+  keeps the older `agentdir --upgrade` interface working for compatibility.
+- Coexist with rulesync by installing AgentDir guidance at
+  `.rulesync/rules/agentdir.md` instead of editing generated tool files. Files
+  with generated headers are protected unless `--force` is explicitly used.
+- Detect lefthook, husky, pre-commit, and `core.hooksPath`; record installed
+  shims in `.agentdir/hooks.json`; warn when another tool replaces them; and
+  safely restore known hook-manager scripts without discarding custom hooks.
+- Install hooks into the directory Git actually uses, including linked
+  worktrees and repositories configured with `core.hooksPath`.
+- Clarify the README's generated-file and active-hooks-directory layout, and
+  document when the optional semantic retrieval dependencies are worthwhile.
+
+## Install Or Update
+
+Install from PyPI:
+
+```bash
+uv tool install agentdir-cli
+# or
+pipx install agentdir-cli
+```
+
+Update an existing installation:
+
+```bash
+agentdir update
+```
+
+Or use the release installer:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/jstxn/agentdir/main/scripts/install.sh | bash
+```
+
+Install the Pi package from npm or the release tag:
+
+```bash
+pi install npm:@jstxn/agentdir-pi@0.7.7
+pi install git:github.com/jstxn/agentdir@v0.7.7
+```
+
+Rollback to v0.7.6 is one command:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/jstxn/agentdir/main/scripts/rollback.sh | bash
+```

{agentdir_cli-0.7.5 → agentdir_cli-0.7.7}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jstxn/agentdir-pi",
-  "version": "0.7.5",
+  "version": "0.7.7",
   "description": "Pi package for AgentDir local-first coding-agent memory and evidence capture.",
   "license": "MIT",
   "keywords": [
@@ -29,6 +29,6 @@
     "skills": [
       "./skills"
     ],
-    "image": "https://raw.githubusercontent.com/jstxn/agentdir/v0.7.5/docs/assets/agentdir-overview.png"
+    "image": "https://raw.githubusercontent.com/jstxn/agentdir/v0.7.7/docs/assets/agentdir-overview.png"
   }
 }

{agentdir_cli-0.7.5 → agentdir_cli-0.7.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentdir-cli"
-version = "0.7.5"
+version = "0.7.7"
 description = "Local-first Maildir-inspired work mailstore for software agents"
 readme = "README.md"
 requires-python = ">=3.11"

{agentdir_cli-0.7.5 → agentdir_cli-0.7.7}/scripts/install.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-AGENTDIR_VERSION="${AGENTDIR_VERSION:-v0.7.5}"
+AGENTDIR_VERSION="${AGENTDIR_VERSION:-v0.7.7}"
 AGENTDIR_REPO="${AGENTDIR_REPO:-jstxn/agentdir}"
 AGENTDIR_PACKAGE_VERSION="${AGENTDIR_VERSION#v}"
 # Releases after v0.7.4 ship the wheel under the agentdir-cli distribution

{agentdir_cli-0.7.5 → agentdir_cli-0.7.7}/scripts/rollback.sh

@@ -2,7 +2,7 @@
 set -euo pipefail
 
 AGENTDIR_REPO="${AGENTDIR_REPO:-jstxn/agentdir}"
-AGENTDIR_ROLLBACK_VERSION="${1:-${AGENTDIR_ROLLBACK_VERSION:-v0.7.4}}"
+AGENTDIR_ROLLBACK_VERSION="${1:-${AGENTDIR_ROLLBACK_VERSION:-v0.7.6}}"
 AGENTDIR_TMP_DIR=""
 
 log() {

{agentdir_cli-0.7.5 → agentdir_cli-0.7.7}/skills/agentdir/SKILL.md

@@ -56,6 +56,14 @@ Use `agentdir evidence --brief` and `agentdir timeline` to skim what has been re
 
 Emit important plans, blockers, diffs, review decisions, and final handoffs as immutable events when they matter for future replay or audit.
 
+## Exit Codes And Structured Errors
+
+- 0 success; `agentdir run` passes through the wrapped command's exit code (124 = `--timeout` kill).
+- 2 user error, 3 state error (no root / no active session), 4 missing dependency, 5 configuration error.
+- State errors name the recovery command in the message (`agentdir adopt`, `agentdir work start`).
+- Add `--json` to get a `{"success": false, "exit_code": ..., "error_code": ...}` envelope on failure; add `--quiet` for exit-code-only checks.
+- `agentdir run --session require` fails fast instead of auto-creating a session; `--session create` forces a fresh one.
+
 ## Finish Work
 
 Before the final response, run `agentdir work finish --json` when practical. Read the `agent_handoff` object before making final verification claims.

{agentdir_cli-0.7.5 → agentdir_cli-0.7.7}/src/agentdir/__init__.py

@@ -1,3 +1,3 @@
 """AgentDir local agent work mailstore."""
 
-__version__ = "0.7.5"
+__version__ = "0.7.7"