@jstxn/agentdir-pi 0.7.4 → 0.7.8

package/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">
@@ -78,23 +78,25 @@ agentdir work finish --json
 
 ## Install
 
-AgentDir is distributed through GitHub Releases. For the private
-`jstxn/agentdir` repo, authenticate GitHub CLI first:
+Install from PyPI (the package is `agentdir-cli`; the command it installs is
+`agentdir`):
 
 ```bash
-gh auth login
+uv tool install agentdir-cli
+# or
+pipx install agentdir-cli
 ```
 
-Install the latest release:
+Or use the GitHub Release installer:
 
 ```bash
-gh api -H "Accept: application/vnd.github.raw" \
-  'repos/jstxn/agentdir/contents/scripts/install.sh?ref=v0.7.4' | bash
+curl -fsSL https://raw.githubusercontent.com/jstxn/agentdir/main/scripts/install.sh | bash
 ```
 
 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:
 
@@ -103,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
@@ -111,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.4
+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>
@@ -130,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:
 
@@ -157,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
@@ -165,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
@@ -178,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
 
@@ -341,8 +379,7 @@ agentdir --upgrade
 Rollback to the previous stable release:
 
 ```bash
-gh api -H "Accept: application/vnd.github.raw" \
-  'repos/jstxn/agentdir/contents/scripts/rollback.sh?ref=v0.7.4' | bash
+curl -fsSL https://raw.githubusercontent.com/jstxn/agentdir/main/scripts/rollback.sh | bash
 ```
 
 ## Learn More

package/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.4
+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.4/docs/assets/agentdir-overview.png"
+    "image": "https://raw.githubusercontent.com/jstxn/agentdir/v0.7.8/docs/assets/agentdir-overview.png"
   }
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jstxn/agentdir-pi",
-  "version": "0.7.4",
+  "version": "0.7.8",
   "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.4/docs/assets/agentdir-overview.png"
+    "image": "https://raw.githubusercontent.com/jstxn/agentdir/v0.7.8/docs/assets/agentdir-overview.png"
   }
 }

package/skills/agentdir/SKILL.md

@@ -21,7 +21,7 @@ This Pi package teaches Pi how to operate AgentDir. It does not install the `age
 
 At the start of a non-trivial coding task in a software repository:
 
-1. If `.agentdir` is missing, run `agentdir adopt` once before work begins.
+1. If `.agentdir` is missing, run `agentdir adopt --gitignore user` once so the local store stays out of Git without changing the repository's `.gitignore`.
 2. Start the session with `agentdir work start "<short task>" --emit-context`.
 3. Keep any returned context pack id/source ids if you plan to cite or consume retrieved context later.
 
@@ -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.