agentdir-cli 0.7.6__tar.gz → 0.7.8__tar.gz

{agentdir_cli-0.7.6/src/agentdir_cli.egg-info → agentdir_cli-0.7.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentdir-cli
-Version: 0.7.6
+Version: 0.7.8
 Summary: Local-first Maildir-inspired work mailstore for software agents
 Author: AgentDir Contributors
 License-Expression: MIT
@@ -128,7 +128,8 @@ curl -fsSL https://raw.githubusercontent.com/jstxn/agentdir/main/scripts/install
 
 The installer uses `pipx` when available. Otherwise it creates a self-contained
 virtual environment under `~/.local/share/agentdir` and links the CLI into
-`~/.local/bin`.
+`~/.local/bin`. It does not edit Git configuration or ignore files; after
+installation it prints the explicit adoption choices.
 
 Verify:
 
@@ -137,6 +138,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 +156,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.6
+pi install npm:@jstxn/agentdir-pi@0.7.8
 # 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>
@@ -164,6 +175,13 @@ Run once from a git repository:
 agentdir adopt
 ```
 
+Coding agents use the non-interactive form below so `.agentdir/` is ignored at
+the user level without creating a repository `.gitignore` change:
+
+```bash
+agentdir adopt --gitignore user
+```
+
 This is intentionally boring setup. It prepares the repository once, then agents
 operate AgentDir during normal coding work:
 
@@ -191,6 +209,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
@@ -199,6 +227,10 @@ agentdir adopt --gitignore user     # write the user-level Git excludes file
 agentdir adopt --gitignore none     # leave ignore files unchanged
 ```
 
+Generated AgentDir guidance selects `--gitignore user` by default. The plain
+interactive command still prompts, and all three explicit choices remain
+available.
+
 Undo managed setup while keeping the `.agentdir` evidence store:
 
 ```bash
@@ -212,17 +244,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.6 → agentdir_cli-0.7.8}/README.md

@@ -95,7 +95,8 @@ curl -fsSL https://raw.githubusercontent.com/jstxn/agentdir/main/scripts/install
 
 The installer uses `pipx` when available. Otherwise it creates a self-contained
 virtual environment under `~/.local/share/agentdir` and links the CLI into
-`~/.local/bin`.
+`~/.local/bin`. It does not edit Git configuration or ignore files; after
+installation it prints the explicit adoption choices.
 
 Verify:
 
@@ -104,6 +105,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 +123,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.6
+pi install npm:@jstxn/agentdir-pi@0.7.8
 # 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>
@@ -131,6 +142,13 @@ Run once from a git repository:
 agentdir adopt
 ```
 
+Coding agents use the non-interactive form below so `.agentdir/` is ignored at
+the user level without creating a repository `.gitignore` change:
+
+```bash
+agentdir adopt --gitignore user
+```
+
 This is intentionally boring setup. It prepares the repository once, then agents
 operate AgentDir during normal coding work:
 
@@ -158,6 +176,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
@@ -166,6 +194,10 @@ agentdir adopt --gitignore user     # write the user-level Git excludes file
 agentdir adopt --gitignore none     # leave ignore files unchanged
 ```
 
+Generated AgentDir guidance selects `--gitignore user` by default. The plain
+interactive command still prompts, and all three explicit choices remain
+available.
+
 Undo managed setup while keeping the `.agentdir` evidence store:
 
 ```bash
@@ -179,17 +211,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.6 → agentdir_cli-0.7.8}/docs/AGENTIC_CODING.md

@@ -27,6 +27,15 @@ From a git repository:
 agentdir adopt
 ```
 
+For agent-driven, non-interactive setup, make the ignore destination explicit:
+
+```bash
+agentdir adopt --gitignore user
+```
+
+This keeps `.agentdir/` out of Git across repositories without changing a
+project's tracked `.gitignore`.
+
 This initializes `.agentdir`, installs managed Git hook shims, installs the
 Codex skill in the user skill directory, writes broad project guidance for
 common agent tools, asks interactive users where to ignore `.agentdir/`, runs
@@ -54,7 +63,7 @@ The user should not have to operate AgentDir during a normal coding session. Onc
 Agent responsibilities:
 
 - run `agentdir work start "<task>" --emit-context` when coding work begins
-- run `agentdir adopt` once if the repository has not been prepared yet
+- run `agentdir adopt --gitignore user` once if the repository has not been prepared yet
 - use `agentdir status` when a single health view is needed
 - emit context packs when retrieved context materially informs the work
 - record which context sources were consumed and cited when reporting lineage
@@ -87,7 +96,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 +166,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.6 → agentdir_cli-0.7.8}/docs/INSTALL.md

@@ -28,6 +28,17 @@ The installer downloads release assets anonymously with `curl`. If `curl` is
 unavailable or the download fails, it falls back to authenticated GitHub CLI
 (`gh auth login`).
 
+The installer does not modify Git configuration or ignore files. It prints a
+post-install command that agents can use from a repository:
+
+```bash
+agentdir adopt --gitignore user
+```
+
+This appends `.agentdir/` to the configured user-level Git excludes file. Use
+`--gitignore project` for a repository `.gitignore` entry or `--gitignore none`
+to leave ignore files unchanged.
+
 The installer downloads the release wheel and installs it with `pipx` when available. If `pipx` is not installed, it falls back to a self-contained virtual environment at:
 
 ```text
@@ -48,27 +59,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.6
-agentdir --upgrade --upgrade-dry-run
+agentdir update --install-skill none
+agentdir update --no-adopt
+agentdir update --version v0.7.8
+agentdir update --dry-run
 ```
 
+The older `agentdir --upgrade` interface and its `--upgrade-*` options remain
+supported for compatibility.
+
 ## Verify Install
 
 ```bash
@@ -79,7 +93,7 @@ repo="$(mktemp -d)/agentdir-install-smoke"
 mkdir -p "$repo"
 git -C "$repo" init
 cd "$repo"
-agentdir adopt --install-skill store
+agentdir adopt --install-skill store --gitignore user
 agentdir work start "install smoke" --emit-context
 agentdir run -- python3 -c "print('agentdir install smoke')"
 agentdir evidence --brief
@@ -96,13 +110,13 @@ agentdir work finish --json
 If you already have the wheel asset:
 
 ```bash
-AGENTDIR_WHEEL=/path/to/agentdir_cli-0.7.6-py3-none-any.whl bash scripts/install.sh
+AGENTDIR_WHEEL=/path/to/agentdir_cli-0.7.8-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.6-py3-none-any.whl bash scripts/install.sh
+AGENTDIR_FORCE_VENV=1 AGENTDIR_WHEEL=/path/to/agentdir_cli-0.7.8-py3-none-any.whl bash scripts/install.sh
 ```
 
 ## Roll Back To The Previous Release
@@ -119,13 +133,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.5
+curl -fsSL https://raw.githubusercontent.com/jstxn/agentdir/main/scripts/rollback.sh | bash -s -- v0.7.7
 ```
 
 The equivalent manual rollback is:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/jstxn/agentdir/main/scripts/install.sh | AGENTDIR_VERSION=v0.7.5 bash
+curl -fsSL https://raw.githubusercontent.com/jstxn/agentdir/main/scripts/install.sh | AGENTDIR_VERSION=v0.7.7 bash
 ```
 
 ## Optional Extras
@@ -143,6 +157,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 +275,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.6 → agentdir_cli-0.7.8}/docs/PI_PACKAGE.md

@@ -9,7 +9,9 @@ skills/agentdir/SKILL.md
 
 The skill teaches Pi to start AgentDir sessions, wrap evidence-bearing shell
 commands, use local memory/context packs, and produce evidence-aware handoffs.
-It does not install the `agentdir` CLI; install AgentDir separately first.
+It also tells Pi to adopt unprepared repositories with `--gitignore user`, so
+the local store stays out of Git without changing project files. It does not
+install the `agentdir` CLI; install AgentDir separately first.
 
 ## Install
 
@@ -34,7 +36,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.6
+pi install npm:@jstxn/agentdir-pi@0.7.8
 ```
 
 Use `pi config` to enable or disable the bundled skill after installation.
@@ -48,7 +50,7 @@ The root `package.json` declares the Pi resources:
   "keywords": ["pi-package"],
   "pi": {
     "skills": ["./skills"],
-    "image": "https://raw.githubusercontent.com/jstxn/agentdir/v0.7.6/docs/assets/agentdir-overview.png"
+    "image": "https://raw.githubusercontent.com/jstxn/agentdir/v0.7.8/docs/assets/agentdir-overview.png"
   }
 }
 ```

{agentdir_cli-0.7.6 → agentdir_cli-0.7.8}/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.6-py3-none-any.whl
-dist/agentdir_cli-0.7.6.tar.gz
-dist/jstxn-agentdir-pi-0.7.6.tgz
+dist/agentdir_cli-0.7.8-py3-none-any.whl
+dist/agentdir_cli-0.7.8.tar.gz
+dist/jstxn-agentdir-pi-0.7.8.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.6 -m "Release AgentDir v0.7.6"
+git tag -a v0.7.8 -m "Release AgentDir v0.7.8"
 git push origin main
-git push origin v0.7.6
+git push origin v0.7.8
 
-gh release create v0.7.6 \
-  dist/agentdir_cli-0.7.6-py3-none-any.whl \
-  dist/agentdir_cli-0.7.6.tar.gz \
-  dist/jstxn-agentdir-pi-0.7.6.tgz \
+gh release create v0.7.8 \
+  dist/agentdir_cli-0.7.8-py3-none-any.whl \
+  dist/agentdir_cli-0.7.8.tar.gz \
+  dist/jstxn-agentdir-pi-0.7.8.tgz \
   dist/install-agentdir.sh \
   dist/rollback-agentdir.sh \
   --repo jstxn/agentdir \
-  --title "AgentDir v0.7.6" \
-  --notes-file docs/releases/v0.7.6.md
+  --title "AgentDir v0.7.8" \
+  --notes-file docs/releases/v0.7.8.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.6 --repo jstxn/agentdir --pattern install-agentdir.sh --dir "$tmp"
+gh release download v0.7.8 --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
@@ -79,7 +79,7 @@ mkdir -p "$repo"
 git -C "$repo" init
 printf 'release smoke\n' > "$tmp/body.txt"
 cd "$repo"
-"$tmp/prefix/bin/agentdir" adopt --install-skill store
+"$tmp/prefix/bin/agentdir" adopt --install-skill store --gitignore user
 "$tmp/prefix/bin/agentdir" work start "release smoke" --emit-context
 "$tmp/prefix/bin/agentdir" run -- python3 -c "print('release smoke')"
 "$tmp/prefix/bin/agentdir" context build "release smoke"
@@ -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.6-py3-none-any.whl" \
+AGENTDIR_WHEEL="$PWD/dist/agentdir_cli-0.7.8-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.5
+  bash dist/rollback-agentdir.sh v0.7.7
 
 "$tmp/prefix/bin/agentdir" --help
 ```

{agentdir_cli-0.7.6 → agentdir_cli-0.7.8}/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.8/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
+```