diff --git a/.github/scripts/test-bootstrap-state.sh b/.github/scripts/test-bootstrap-state.sh
new file mode 100755
index 0000000..b961939
--- /dev/null
+++ b/.github/scripts/test-bootstrap-state.sh
@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+#
+# Unit tests for strip_host_hooks() in the devcontainer bootstrap script.
+#
+# Sources the template (made importable by its exec-guard) and exercises the
+# hook-stripping logic on fixture settings.json blobs: gryph/cot commands are
+# removed, rtk + user hooks are preserved, emptied events are pruned, the
+# transform is idempotent, and malformed/missing input doesn't crash.
+#
+# Run:   .github/scripts/test-bootstrap-state.sh
+# CI:    wired into .github/workflows/shellcheck.yml
+set -euo pipefail
+
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+repo_root="$(cd "$here/../.." && pwd)"
+tmpl="$repo_root/templates/devcontainer/scripts/bootstrap-state.sh.tmpl"
+
+# Source the prod template. Its exec-guard stops the init/sync dispatch from
+# firing; we only want the strip_host_hooks() definition.
+# shellcheck source=../../../templates/devcontainer/scripts/bootstrap-state.sh.tmpl
+# shellcheck disable=SC1090
+source "$tmpl"
+
+pass=0
+fail=0
+assert_eq() { # <label> <expected> <actual>
+  if [[ "$2" == "$3" ]]; then
+    printf '  ok   %s\n' "$1"; pass=$((pass + 1))
+  else
+    printf '  FAIL %s\n      expected: %s\n      actual:   %s\n' "$1" "$2" "$3" >&2
+    fail=$((fail + 1))
+  fi
+}
+
+tmp="$(mktemp -d)"
+trap 'rm -rf "$tmp"' EXIT
+
+# --- Case 1: mixed PreToolUse keeps rtk, drops gryph; cot/gryph events pruned
+f1="$tmp/c1.json"
+cat >"$f1" <<'JSON'
+{
+  "model": "opus",
+  "hooks": {
+    "PreToolUse": [
+      {"matcher": "*", "hooks": [{"type": "command", "command": "gryph _hook claude-code PreToolUse"}]},
+      {"matcher": "Bash", "hooks": [{"type": "command", "command": "rtk hook claude"}]}
+    ],
+    "UserPromptSubmit": [
+      {"hooks": [{"type": "command", "command": "/Users/ion1/.cot/bin/cot hook claude"}]}
+    ],
+    "Stop": [
+      {"hooks": [{"type": "command", "command": "cot hook claude"}]}
+    ],
+    "Notification": [
+      {"hooks": [{"type": "command", "command": "gryph _hook claude-code Notification"}]}
+    ]
+  }
+}
+JSON
+strip_host_hooks "$f1"
+assert_eq "only PreToolUse event survives" '["PreToolUse"]' "$(jq -c '.hooks | keys' "$f1")"
+assert_eq "PreToolUse keeps rtk entry only" \
+  '[{"matcher":"Bash","hooks":[{"type":"command","command":"rtk hook claude"}]}]' \
+  "$(jq -c '.hooks.PreToolUse' "$f1")"
+assert_eq "non-hook keys preserved" 'opus' "$(jq -r '.model' "$f1")"
+
+# --- Case 2: a user hook next to a host hook in the same entry is preserved --
+f2="$tmp/c2.json"
+cat >"$f2" <<'JSON'
+{
+  "hooks": {
+    "PreToolUse": [
+      {"matcher": "*", "hooks": [
+        {"type": "command", "command": "gryph _hook claude-code PreToolUse"},
+        {"type": "command", "command": "/usr/local/bin/myfmt --check"}
+      ]}
+    ]
+  }
+}
+JSON
+strip_host_hooks "$f2"
+assert_eq "user hook preserved" '/usr/local/bin/myfmt --check' \
+  "$(jq -r '.hooks.PreToolUse[0].hooks[0].command' "$f2")"
+
+# --- Case 3: idempotent — a second pass is a byte-for-byte no-op -------------
+strip_host_hooks "$f1"
+cp "$f1" "$tmp/c1.once"
+strip_host_hooks "$f1"
+if cmp -s "$tmp/c1.once" "$f1"; then
+  assert_eq "idempotent on re-run" "same" "same"
+else
+  assert_eq "idempotent on re-run" "same" "different"
+fi
+
+# --- Case 4: nothing to strip -> file bytes unchanged -----------------------
+f4="$tmp/c4.json"
+printf '{"hooks":{"PreToolUse":[{"matcher":"Bash","hooks":[{"type":"command","command":"rtk hook claude"}]}]}}' >"$f4"
+before="$(cat "$f4")"
+strip_host_hooks "$f4"
+assert_eq "no rewrite when nothing matches" "$before" "$(cat "$f4")"
+
+# --- Case 5: malformed JSON exits 0 and leaves the file untouched -----------
+f5="$tmp/c5.json"
+printf 'this is not json' >"$f5"
+strip_host_hooks "$f5" && rc=0 || rc=$?
+assert_eq "malformed JSON exits 0" '0' "$rc"
+assert_eq "malformed file untouched" 'this is not json' "$(cat "$f5")"
+
+# --- Case 6: missing file is a no-op (exit 0) -------------------------------
+strip_host_hooks "$tmp/does-not-exist.json" && rc=0 || rc=$?
+assert_eq "missing file exits 0" '0' "$rc"
+
+echo
+echo "passed=$pass failed=$fail"
+[[ "$fail" -eq 0 ]] || exit 1
diff --git a/.github/workflows/aidc-e2e.yml b/.github/workflows/aidc-e2e.yml
index 4131bc7..d4a036a 100644
--- a/.github/workflows/aidc-e2e.yml
+++ b/.github/workflows/aidc-e2e.yml
@@ -191,6 +191,9 @@ jobs:
             .ai-container/project.env \
             CLAUDE.md \
             AGENTS.md \
+            CHANGELOG.md \
+            DETAILED_CHANGELOG.md \
+            logs/README.md \
             .cursor/rules/00-core-logics.mdc; do
             [ -f "$work/$f" ] || fail "init did not create $f"
           done
@@ -198,6 +201,12 @@ jobs:
           grep -q '^AIDC_REPO_SLUG=' "$work/.ai-container/project.env" \
             || fail "project.env missing AIDC_REPO_SLUG"
 
+          # Documentation seeds are copy-once: a hand-edit must survive re-init.
+          echo "EDITED-BY-USER" >> "$work/CHANGELOG.md"
+          ( cd "$work" && aidc init ) || fail "second aidc init failed"
+          grep -q 'EDITED-BY-USER' "$work/CHANGELOG.md" \
+            || fail "re-init clobbered a user edit to CHANGELOG.md"
+
           # Re-running init over an initialized repo must be a clean no-op.
           ( cd "$work" && aidc init ) || fail "second aidc init was not idempotent"
           echo "init scaffold OK"
diff --git a/.github/workflows/shellcheck.yml b/.github/workflows/shellcheck.yml
index ddf6852..80db9ec 100644
--- a/.github/workflows/shellcheck.yml
+++ b/.github/workflows/shellcheck.yml
@@ -33,3 +33,6 @@ jobs:
 
       - name: Syntax-check Python clipboard server
         run: python3 -m py_compile bin/aidc-clipboard-server
+
+      - name: Run bootstrap unit tests
+        run: .github/scripts/test-bootstrap-state.sh
diff --git a/.gitignore b/.gitignore
index c1f25bd..ad91899 100644
--- a/.gitignore
+++ b/.gitignore
@@ -19,7 +19,7 @@ references/
 # the source of truth; the generated copies at the repo root are local-only.
 /CLAUDE.md
 /AGENTS.md
-
+/logs
 # Editor / OS noise
 .DS_Store
 *.swp
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3a9fc28..62d1c22 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,12 @@ All notable changes to aidc are tracked here. Format follows [Keep a Changelog](
 
 ### Added
 
+- **On-demand Claude OAuth token from the macOS Keychain.** `aidc claude` now reads `CLAUDE_CODE_OAUTH_TOKEN` straight from the Keychain (service `claude-code-oauth-token`, your `$USER` account) when it isn't already in the environment, so the token no longer has to be exported into every shell via `~/.zshrc`. An existing env var still wins (back-compat); override the service name or disable the lookup with `AIDC_CLAUDE_OAUTH_KEYCHAIN_SERVICE` (set empty to disable); no-op on hosts without `security`. Dropping `CLAUDE_CODE_OAUTH_TOKEN` from `AIDC_PASSTHROUGH_ENV_KEYS` (per-project via `.ai-container/project.env`) disables both forwarding and the Keychain lookup for that container. Covered by `tests/resolve-oauth-token.test.sh`.
+- **Automatic session sync.** In-container agent transcripts now sync to the host on container start (down→up transition), agent exit, `aidc down`, and `aidc destroy` (synced before `-v` removes the volumes), so `/insights` stays current without a manual `aidc sync-sessions`. The start sync is the recovery path for ungraceful exits (crash / `docker kill`) the on-exit hooks can't cover. Toggle with `AIDC_AUTO_SYNC_SESSIONS` host-wide in `~/.config/aidc/config.env` or per project in `.ai-container/project.env` (per-folder overrides global). The agent's exit code is preserved across the post-run sync.
+- **Host-wide config file.** New `~/.config/aidc/config.env` holds universal aidc defaults for every project; `.ai-container/project.env` is sourced after it and overrides per folder. Seeded (fully commented) on first run.
+- **`aidc rescan` command.** Re-detects project languages and rebuilds so a repo that started empty (or single-language) picks up the matching toolchains and security scanners once code lands. Prints detected vs. effective (overridden) toolchains before building.
+- **`shell` toolchain → shellcheck.** `aidc::detect_toolchains` now detects shell scripts (any `*.sh` file, or an extensionless executable with a shell shebang such as `bin/aidc`) and installs `shellcheck` via a new `shell)` arm in the Dockerfile toolchain block.
+- **Project documentation seeds.** `aidc init` now seeds `CHANGELOG.md`, `DETAILED_CHANGELOG.md`, and `logs/README.md` into each project once (never overwritten, and intentionally not git-excluded so they are committed). The scaffolded `CLAUDE.md`/`AGENTS.md` guidance gains **Testing & coverage**, **Documentation & changelog**, **Documentation requirements**, and **Session log convention** sections, plus a `shellcheck` line in the security guardrails.
 - **Grok Build agent.** `aidc grok` launches xAI's Grok Build CLI inside the container, with a `grok_home` named volume (`~/.grok`), a read-only `/host-seed/grok` seed mount, `sync_grok` seeding in `bootstrap-state.sh`, and `aidc sync-config`/`sync-sessions` support. Grok reads the same generated `AGENTS.md`.
 - **GPL-3.0 license.** `LICENSE` at repo root.
 - **Vulnerability disclosure policy.** `SECURITY.md` documents scope, reporting channels, and timelines.
@@ -28,6 +34,8 @@ All notable changes to aidc are tracked here. Format follows [Keep a Changelog](
 - **Pinned `gitleaks` and `vet` versions** in `templates/devcontainer/Dockerfile.tmpl` (`v8.30.1` and `v1.17.3` respectively). Defaults were `latest`, which resolved at build time and defeated the surrounding base-image SHA pin. Repin instructions are in the Dockerfile.
 - **README** and the docs/ tree brought into sync with the above. README's command list includes `aidc status`, `aidc down`, `aidc destroy`, `aidc exec`, and `aidc sync-sessions`. `docs/security.md` covers the scanners, supply-chain guardrails, and egress firewall; `docs/claude-profiles.md` covers the local-model profiles (`localhost.env.example`, `localnetwork.env.example`).
 
+- **VM Claude hooks are now rtk-only.** The host-seed `settings.json` carries hooks for host-only tools (`gryph`, and `cot` on a hard-coded macOS path) that are pointless or broken inside the container. `bootstrap-state.sh` now strips just those entries on every `sync_claude` (preserving rtk and any user hooks; self-heals volumes seeded by an older bootstrap), and `install_agent_hooks` wires only `rtk init --global --auto-patch --hook-only` (non-interactive; installs just the hook without re-writing `CLAUDE.md`/`RTK.md`). In-container session transcripts already auto-sync to the host on start/exit, so agent observability stays host-side.
+
 ### Fixed
 
 - **RTK install path.** Dockerfile previously set `RTK_INSTALL_DIR=/usr/local/bin` on the wrong side of the pipe (`VAR=val cmd1 | cmd2` scopes `VAR` to `cmd1`), so the installer fell back to `$HOME/.local/bin` while running as root — the binary landed in `/root/.local/bin/rtk` and was invisible to the `vscode` user. Env var moved onto the `sh` side of the pipe.
@@ -36,4 +44,6 @@ All notable changes to aidc are tracked here. Format follows [Keep a Changelog](
 
 - **AWS Bedrock and Google Vertex support.** `/host-auth/aws` and `/host-auth/gcloud` bind mounts dropped. `AIDC_AWS_SOURCE`, `AIDC_GCLOUD_SOURCE`, `bedrock.env.example`, and `vertex.env.example` removed. AWS- and Google-specific keys (`AWS_PROFILE`, `AWS_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, `AWS_DEFAULT_REGION`, `ANTHROPIC_VERTEX_PROJECT_ID`, `CLOUD_ML_REGION`, `GOOGLE_APPLICATION_CREDENTIALS`, `GOOGLE_CLOUD_PROJECT`) dropped from `AIDC_PASSTHROUGH_ENV_KEYS`.
 
+- **gryph removed from the image.** SafeDep's `gryph` agent-audit layer is no longer installed (Dockerfile) or hooked (`gryph install` dropped from `bootstrap-state.sh`); host-side hooks for it are stripped from the seeded `settings.json`. `cot` was never in the image (its hook command pointed at a macOS-only binary path) and is likewise stripped. Agent observability is host-side now that sessions auto-sync on container start and exit.
+
 [Unreleased]: https://github.com/cyfinoid/aidc/commits/main
diff --git a/DETAILED_CHANGELOG.md b/DETAILED_CHANGELOG.md
new file mode 100644
index 0000000..d117710
--- /dev/null
+++ b/DETAILED_CHANGELOG.md
@@ -0,0 +1,222 @@
+# Detailed Changelog
+
+The long-form companion to `CHANGELOG.md`. Where `CHANGELOG.md` says *what*
+changed in one line, this file records *why* and *how* — enough for a future
+reader to audit, reproduce, or roll back any change without re-deriving it.
+
+Add a new entry (newest first) for every meaningful change.
+
+---
+
+## 2026-06-26 — Resolve Claude OAuth token from the macOS Keychain on demand
+
+**Summary:** `aidc claude` now fetches `CLAUDE_CODE_OAUTH_TOKEN` from the macOS
+Keychain at exec time when it isn't already exported, removing the need for the
+`~/.zshrc` line that broadcast the token to every shell process.
+
+**Why:** The documented setup put
+
+```bash
+export CLAUDE_CODE_OAUTH_TOKEN="$(security find-generic-password -a "$USER" -s claude-code-oauth-token -w 2>/dev/null)"
+```
+
+in `~/.zshrc`. That works, but it exports the plaintext token into the
+environment of *every* process the shell spawns, for the whole session — far
+wider exposure than needed. The token only has to exist for the brief
+`docker compose exec` that launches Claude inside the container. Moving the
+Keychain read into `aidc` shrinks the token's lifetime to that single call and
+keeps it out of unrelated processes' environments.
+
+**How it works:** `aidc::run_tool` calls a new `aidc::resolve_claude_oauth_token`
+on the `claude` path, before the existing env passthrough
+(`aidc::append_passthrough_env_args`) and the `aidc-bootstrap-claude` one-time
+login step — both of which already read `CLAUDE_CODE_OAUTH_TOKEN` from `aidc`'s
+own process env, so populating it there is all that's needed. Resolution order:
+
+1. `CLAUDE_CODE_OAUTH_TOKEN` already set → used as-is (back-compat with the old
+   `~/.zshrc` export and with CI secrets).
+2. Else `security find-generic-password -a "$USER" -s "$service" -w` →
+   exported into `aidc`'s env only.
+3. Else unchanged (interactive login / profile auth).
+
+It is a deliberate no-op when: the var is already set; `CLAUDE_CODE_OAUTH_TOKEN`
+has been removed from `AIDC_PASSTHROUGH_ENV_KEYS` (per-project opt-out); the
+service name `AIDC_CLAUDE_OAUTH_KEYCHAIN_SERVICE` is empty; or `security` is not
+on `PATH` (non-macOS hosts). The token value is never logged.
+
+**What changed:**
+- `lib/aidc.sh`:
+  - New `AIDC_CLAUDE_OAUTH_KEYCHAIN_SERVICE` default (`claude-code-oauth-token`),
+    overridable/disable-able via `~/.config/aidc/config.env`.
+  - New `aidc::resolve_claude_oauth_token` (account falls back to `id -un` when
+    `$USER` is unset, so it is safe under `set -u`).
+  - Wired into `aidc::run_tool` ahead of the passthrough/bootstrap, gated to the
+    `claude` tool so codex/opencode/grok containers don't receive an unused
+    credential.
+  - Seeded a commented `AIDC_CLAUDE_OAUTH_KEYCHAIN_SERVICE` entry in the
+    generated global config (`aidc::ensure_global_config`).
+- `tests/resolve-oauth-token.test.sh`: new self-contained test that stubs
+  `security` on `PATH` and covers all seven branches (preset wins; resolve +
+  no-leak; empty result; failed lookup; disabled service; passthrough opt-out;
+  missing `security`).
+- Docs: a new **Claude authentication** section in `README.md` documents the
+  recommended flow (`claude setup-token` → store under the `claude-code-oauth-token`
+  Keychain item → aidc reads it at runtime), with an explicit warning against
+  using the short-lived `accessToken` from Claude Code's own
+  `Claude Code-credentials` Keychain item. `docs/claude-profiles.md` Option A
+  rewritten (the `~/.zshrc` export is now optional); `docs/security.md` documents
+  the on-demand lookup and the per-container passthrough override.
+
+**Commands / verification:**
+```bash
+bash tests/resolve-oauth-token.test.sh   # 7 passed, 0 failed
+shellcheck lib/aidc.sh tests/resolve-oauth-token.test.sh
+semgrep scan --config auto lib/aidc.sh tests/
+gitleaks detect --no-banner
+```
+
+End-to-end on a Mac (token in Keychain, `CLAUDE_CODE_OAUTH_TOKEN` unset):
+`aidc claude` authenticates with no interactive login, `aidc exec -- printenv
+CLAUDE_CODE_OAUTH_TOKEN` shows the token reached the container, and `printenv
+CLAUDE_CODE_OAUTH_TOKEN` in the parent shell stays empty.
+
+**Notes:** macOS-only by design (matches the project's documented "host-side bits
+assume Mac" stance); other hosts fall through to the existing env/profile/login
+paths unchanged. A future resolver hook could generalise this to 1Password /
+`pass` / Vault, but that was intentionally out of scope here.
+
+Decision — raw setup-token, not the subscription `accessToken`. Claude Code on
+macOS keeps its own Keychain item (`Claude Code-credentials`) holding a JSON blob
+with `claudeAiOauth.accessToken` + `refreshToken`. That `accessToken` is
+short-lived (hours) and only refreshed when Claude Code runs on the host, so it
+goes stale for container-only use. Rather than parse/extract it (and depend on
+host refresh), aidc reads the long-lived token from `claude setup-token`, stored
+as a raw value under `claude-code-oauth-token`. The resolver therefore stays a
+plain raw-string read — no JSON parsing, no `refreshToken` persisted into a
+volume.
+
+---
+
+## 2026-06-25 — rtk-only VM hooks; drop gryph/cot from the container
+
+**Summary:** The container's Claude Code `settings.json` now carries only the
+rtk token-saving hook. The host-seed hooks for host-only tooling (`gryph`,
+`cot`) are stripped at sync time, `gryph` is no longer installed in the image or
+hooked at bootstrap, and rtk is wired non-interactively by the bootstrap itself.
+
+**Why:** The host's `~/.claude/settings.json` is the seed for the container's
+`settings.json` (copied by `sync_claude`), so it dragged in two classes of hooks
+that don't belong in the VM:
+
+- `gryph _hook claude-code <Event>` — the agent audit layer. Redundant in the VM
+  now that in-container session transcripts auto-sync to the host on container
+  start and exit, so observability already happens on the host.
+- `/Users/ion1/.cot/bin/cot hook claude` — a hard-coded macOS binary path that can
+  never resolve inside the container, so it errored on every `UserPromptSubmit` /
+  `Stop` / `SubagentStop` / `PreCompact` fire.
+
+`gryph install` in `install_agent_hooks` re-added the gryph hooks even if the
+copy were cleaned, so both the seed-copy path and the install path had to change.
+
+**What changed:**
+- `templates/devcontainer/scripts/bootstrap-state.sh.tmpl` (source of truth; the
+  generated `.devcontainer/scripts/bootstrap-state.sh` is byte-identical and is
+  regenerated from this on `aidc rebuild`):
+  - New `strip_host_hooks()` — surgical, idempotent Python that removes only hook
+    commands matching `\bgryph\b|\bcot\b` from a Claude Code `settings.json`,
+    preserves rtk and any user hooks, prunes emptied hook arrays and emptied
+    event keys, and is a no-op (no rewrite) when nothing matches.
+  - `sync_claude()` calls `strip_host_hooks` after seeding `settings.json`, so it
+    runs on every init (self-heals volumes seeded by an older bootstrap, not just
+    fresh copies).
+  - `install_agent_hooks()` no longer runs `gryph install`; it wires only
+    `rtk init --global --auto-patch --hook-only` (non-interactive; adds just the
+    `PreToolUse`/`Bash` hook, no `RTK.md`/`CLAUDE.md` rewrite since both are
+    already seeded from the host).
+  - Added an exec-guard (`[[ "${BASH_SOURCE[0]:-}" == "${0:-}" ]]`, nounset-safe)
+    around the bottom init/sync dispatch so the helper functions are importable by
+    unit tests without triggering side effects.
+- `templates/devcontainer/Dockerfile.tmpl`: removed the `gryph` install `RUN`
+  (curl | sh) and its comment. The new image no longer ships the gryph binary.
+- `.github/scripts/test-bootstrap-state.sh` (new): 9 unit tests for
+  `strip_host_hooks` — mixed PreToolUse keeps rtk/drops gryph, cot/gryph-only
+  events pruned, user hooks preserved, idempotent, no-op when clean, malformed
+  JSON and missing file don't crash.
+- `.github/workflows/shellcheck.yml`: runs the unit tests in CI (ubuntu-latest
+  ships `python3` + `jq`).
+- Docs: `docs/security.md` "Agent guardrails" rewritten rtk-only with the
+  host-side-observability rationale; `README.md`, `docs/install.md`, `SECURITY.md`
+  de-listed `gryph`.
+
+**Commands:**
+- `bash .github/scripts/test-bootstrap-state.sh` → `passed=9 failed=0`.
+- `shellcheck --severity=warning .github/scripts/test-bootstrap-state.sh` and
+  `shellcheck -x templates/devcontainer/scripts/bootstrap-state.sh.tmpl` → clean.
+- `rtk init --global --auto-patch --hook-only` (verified on a throwaway HOME)
+  produces exactly `{"hooks":{"PreToolUse":[{"matcher":"Bash","hooks":[{"type":"command","command":"rtk hook claude"}]}]}}` and no `RTK.md`.
+
+**Verification:**
+- Stripped the live container's `~/.claude/settings.json` in place (backup at
+  `settings.json.bak-pre-rtk-only-20260625T212157Z`): result is rtk-only, valid
+  JSON, 0 `gryph`/`cot` matches.
+- Created `~/.claude/.aidc-agent-hooks-installed` so this running container's
+  stale (read-only) bootstrap won't re-run `gryph install` on restart; confirmed
+  `rtk --version` and `rtk gain` still work (165 cmds, ~65% saved).
+- Scanners: shellcheck clean, `semgrep --config auto --error` exit 0,
+  `gitleaks detect` no leaks, `trufflehog filesystem` 0 secrets. No dependency
+  added (gryph removed), so `vet` SCA scan is N/A.
+
+**Notes:**
+- `.devcontainer/` is read-only inside the container and git-ignored on the host
+  (`.git/info/exclude`); only the template is edited here. `aidc rebuild`
+  regenerates `.devcontainer/*` from the template and rebuilds the image without
+  gryph. A fresh `claude_home` volume (after `aidc destroy`) gets the clean
+  rtk-only state from the new bootstrap.
+- For the currently-running container, the in-place strip + marker makes it
+  stable until the next rebuild; no restart re-adds gryph.
+
+
+
+**Summary:** Added automatic session-sync, a new `aidc rescan` command, shell-script
+detection that installs `shellcheck`, and per-project documentation scaffolding
+(`CHANGELOG.md` / `DETAILED_CHANGELOG.md` / `logs/`), driven by six points of
+real-world usage feedback.
+
+**Why:** Daily use surfaced friction: session-sync was easy to forget; shell scripts
+had no in-container linter; projects that start empty never picked up language
+security tools because detection only ran at first build; and scaffolded projects
+lacked enforced test-coverage and documentation discipline.
+
+**What changed:**
+- `lib/aidc.sh`:
+  - `aidc::auto_sync_sessions` helper (gated on `AIDC_AUTO_SYNC_SESSIONS`, default on),
+    wired into `run_tool` (exit code preserved), `cmd_down`, `cmd_destroy`
+    (before `down -v`), and the container-start transition (`cmd_up`, `cmd_rebuild`,
+    and the lazy-start branch of `ensure_container_running`) as the recovery path for
+    ungraceful exits the on-exit hooks can't cover.
+  - `aidc::has_shell_scripts` + a `shell` entry in `detect_toolchains`.
+  - `aidc::cmd_rescan` + `rescan` dispatch case + help text.
+  - `AIDC_AUTO_SYNC_SESSIONS` documented in `write_project_env`; three
+    `copy_template_once` seed calls in `refresh_scaffold`.
+  - Host-wide config: `AIDC_GLOBAL_CONFIG` (`~/.config/aidc/config.env`),
+    `aidc::load_global_config` sourced first in `load_project_env` (so per-folder
+    `project.env` overrides it), and `aidc::ensure_global_config` seeds a commented
+    template via `ensure_host_config_dirs`. Verified precedence:
+    project.env > config.env > built-in default.
+- `templates/devcontainer/Dockerfile.tmpl`: `shell)` arm installs `shellcheck`.
+- `templates/CLAUDE.md.tmpl` + `templates/AGENTS.md.tmpl`: shellcheck guardrail line;
+  Testing & coverage, Documentation & changelog, Documentation requirements, and
+  Session log convention sections (inside the aidc-managed markers).
+- New seed templates: `templates/CHANGELOG.md.tmpl`,
+  `templates/DETAILED_CHANGELOG.md.tmpl`, `templates/logs/README.md.tmpl`.
+- `README.md` and `CHANGELOG.md` updated; this repo dogfoods the new doc files.
+- `.github/workflows/aidc-e2e.yml`: assert the new seed files appear after `aidc init`.
+
+**How / commands run:** see `logs/2026-06-25-aidc-usability-hardening.md`.
+
+**Verification:** `shellcheck bin/aidc lib/aidc.sh`; bash-compat check; `aidc init`
+scaffold assertions; `semgrep` / `gitleaks` / `trufflehog` on changed files.
+
+**Notes / follow-ups:** `.devcontainer/`, `CLAUDE.md`, and `AGENTS.md` are generated
+artifacts in this repo (listed in `.git/info/exclude`), so only the templates were
+edited — the generated copies refresh from them on the next `aidc up`.
diff --git a/README.md b/README.md
index 0d6e4d5..f7cb8a9 100644
--- a/README.md
+++ b/README.md
@@ -33,12 +33,31 @@ Make sure `~/.local/bin` is on your `PATH`.
 
 ```bash
 cd /path/to/cloned/repo
-aidc init          # one-time scaffold; writes .devcontainer/, .ai-container/, CLAUDE.md, AGENTS.md
+aidc init          # one-time scaffold; writes .devcontainer/, .ai-container/, CLAUDE.md, AGENTS.md, CHANGELOG.md, DETAILED_CHANGELOG.md, logs/
 aidc claude        # auto-runs `aidc up` if needed, then drops you into Claude Code in the container
 ```
 
 Tool commands (`aidc claude` / `codex` / `opencode` / `grok` / `cursor-agent`) auto-bootstrap the container on first run.
 
+## Claude authentication
+
+`aidc claude` needs a Claude credential inside the container. The recommended, durable setup is a **long-lived OAuth token kept in your macOS Keychain** — aidc reads it on demand at runtime, so the token is never exported into every shell and never written to a dotfile.
+
+```bash
+# Mint a long-lived token and store it in the Keychain in one step.
+# `tr -d '[:space:]'` strips the surrounding whitespace/newline so only the token is stored.
+security add-generic-password -U -a "$USER" -s claude-code-oauth-token \
+  -w "$(claude setup-token | rg sk-ant | tr -d '[:space:]')"
+```
+
+No ripgrep? Swap `rg sk-ant` for `grep sk-ant`. You can also run the two steps separately — `claude setup-token` prints the `sk-ant-oat01-…` value, then pass it to `security add-generic-password … -w '<token>'`.
+
+That's it — this is a one-time setup that survives across repos and `aidc destroy`. `aidc claude` resolves `CLAUDE_CODE_OAUTH_TOKEN` from the Keychain on every run (no per-repo login, no `~/.zshrc` export). The first run prompts macOS to allow `security` to read the item — click **Always Allow**.
+
+> **Don't** use the short-lived `accessToken` from Claude Code's own `Claude Code-credentials` Keychain item. That token expires within hours and is only refreshed when you run Claude Code *on the host*, so it goes stale for container-only use. The `claude setup-token` value above is long-lived and built for exactly this.
+
+Already exporting `CLAUDE_CODE_OAUTH_TOKEN` in your shell still works (it takes precedence). Override the Keychain service name — or disable the lookup — with `AIDC_CLAUDE_OAUTH_KEYCHAIN_SERVICE` in `~/.config/aidc/config.env`. Alternate API targets (Z.ai, OpenRouter, local models) use profiles instead — see [`docs/claude-profiles.md`](docs/claude-profiles.md).
+
 ## What aidc actually does
 
 - creates local-only `.devcontainer/`, `.ai-container/`, `CLAUDE.md`, `AGENTS.md`, and `.cursor/rules/00-core-logics.mdc`
@@ -47,19 +66,21 @@ Tool commands (`aidc claude` / `codex` / `opencode` / `grok` / `cursor-agent`) a
 - persists tool state in per-repo Docker volumes instead of mounting whole host homes
 - seeds selected config from host read-only mounts on first startup
 - creates one `CORE_LOGICS` git worktree per repo and mounts it at `/opt/CORE_LOGICS` for shared cross-repo notes
-- detects the project's language toolchains (Go, Rust, Ruby, Java, PHP, Node, Python) and installs them automatically
-- bakes always-on security scanners (`semgrep`, `gitleaks`, `trufflehog`) plus per-toolchain linters (`gosec`, `bandit`, `cargo-audit`, `bundler-audit`) into the image
-- seeds a non-negotiable "Security guardrails" block into `CLAUDE.md` / `AGENTS.md` for every project
-- ships SafeDep's `pmg` / `vet` / `gryph` for supply-chain interception and `rtk` for token-saving CLI proxying
+- detects the project's toolchains (Go, Rust, Ruby, Java, PHP, Node, Python — plus shell scripts) and installs them automatically; `aidc rescan` re-detects later for a repo that started empty
+- bakes always-on security scanners (`semgrep`, `gitleaks`, `trufflehog`) plus per-toolchain linters (`gosec`, `bandit`, `cargo-audit`, `bundler-audit`, `shellcheck`) into the image
+- seeds non-negotiable guidance into `CLAUDE.md` / `AGENTS.md` for every project — security guardrails, test-coverage discipline, and changelog/session-log conventions
+- seeds committed project docs once, never overwriting your edits — `CHANGELOG.md`, `DETAILED_CHANGELOG.md`, and a `logs/` session journal
+- auto-syncs in-container agent session transcripts back to the host on container start and exit, so the host's `/insights` stays current
+- ships SafeDep's `pmg` / `vet` for supply-chain interception and `rtk` for token-saving CLI proxying
 - offers an opt-in default-deny egress firewall with a sane allowlist
 
 ## Documentation
 
 - [`docs/install.md`](docs/install.md) — prereqs, install, daily commands, what lives where, per-project customisation, cleanup
 - [`docs/claude-profiles.md`](docs/claude-profiles.md) — alternate Claude API targets, local-model profiles, one-time OAuth login, session sync
-- [`docs/security.md`](docs/security.md) — scanners, supply-chain guardrails, agent guardrails (gryph + rtk), opt-in egress firewall
+- [`docs/security.md`](docs/security.md) — scanners, supply-chain guardrails, agent guardrails (rtk), opt-in egress firewall
 - [`docs/clipboard-bridge.md`](docs/clipboard-bridge.md) — host-clipboard → container PNG paste bridge
-- [`CHANGELOG.md`](CHANGELOG.md)
+- [`CHANGELOG.md`](CHANGELOG.md) — high-level release notes; [`DETAILED_CHANGELOG.md`](DETAILED_CHANGELOG.md) — long-form per-change rationale
 - [`SECURITY.md`](SECURITY.md) — how to report vulnerabilities in aidc itself
 
 ## Commands
@@ -69,6 +90,7 @@ aidc init [path]
 aidc up [--clipboard] [--isolate-vm]
 aidc down
 aidc rebuild [--clipboard] [--isolate-vm]
+aidc rescan
 aidc status [--global]
 aidc destroy [-f] [--purge-worktree] [--purge-scaffold]
 aidc shell
@@ -86,6 +108,12 @@ aidc sync-sessions [claude|codex|opencode|grok|all]
 
 `aidc status` shows the container + mounts/config for the current folder. `--global` lists every aidc container on the host with disk/CPU/memory and a totals line.
 
+`aidc rescan` re-detects the project's languages and rebuilds, so a repo that started empty (or single-language) picks up the matching toolchains and security scanners once code lands. `shellcheck` installs automatically when shell scripts are present.
+
+Session transcripts auto-sync from the container to the host on container start, agent exit, `aidc down`, and `aidc destroy` (before its volumes are removed), so `/insights` on the host stays current without a manual `aidc sync-sessions`. The start sync is the safety net for ungraceful exits (crash / `docker kill`) that the on-exit hooks miss — it catches up anything left in the volume.
+
+Toggle it with `AIDC_AUTO_SYNC_SESSIONS`: set it host-wide in `~/.config/aidc/config.env` (universal default for every project) or per project in `.ai-container/project.env` (overrides the global default). `0` disables auto-sync; manual `aidc sync-sessions` always works regardless.
+
 `--provider` remains as a compatibility alias for `--profile`.
 
 ## Isolation modes
@@ -137,7 +165,8 @@ echo "AIDC_ISOLATE_VM=1" >> .ai-container/project.env
 
 ## Notes
 
-- Generated files are added to `.git/info/exclude` when the target directory is a git repo, so your project stays clean.
+- Generated files are added to `.git/info/exclude` when the target directory is a git repo, so your project stays clean. The seeded project docs (`CHANGELOG.md`, `DETAILED_CHANGELOG.md`, `logs/`) are *not* excluded — they belong to your repo and are meant to be committed.
+- Settings can be set host-wide in `~/.config/aidc/config.env` (universal defaults for every project) or per project in `.ai-container/project.env`, which overrides the global default. Both files are sourced for env vars like `AIDC_AUTO_SYNC_SESSIONS`, `AIDC_ENABLE_EGRESS_FIREWALL`, and `AIDC_ISOLATE_VM`.
 - Container egress is open by default; set `AIDC_ENABLE_EGRESS_FIREWALL=1` in `.ai-container/project.env` for a default-deny allowlist. See [`docs/security.md`](docs/security.md#optional-egress-firewall).
 - The host-clipboard bridge is **off by default** — no host clipboard socket is mounted into the container. Opt in per (re)create with `aidc up --clipboard` / `aidc rebuild --clipboard`, or persist `AIDC_ENABLE_CLIPBOARD=1` in `.ai-container/project.env`. See [`docs/clipboard-bridge.md`](docs/clipboard-bridge.md).
 - Per-project VM isolation (`--isolate-vm`) is **off by default** due to resource cost. Opt in per (re)create with `aidc up --isolate-vm` / `aidc rebuild --isolate-vm`, or persist `AIDC_ISOLATE_VM=1` in `.ai-container/project.env`. See [Isolation modes](#isolation-modes) above.
diff --git a/SECURITY.md b/SECURITY.md
index 5a7a6ba..cb0ad01 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -9,7 +9,7 @@
 - container hardening defaults (egress firewall, supply-chain shims, scanner pre-installs)
 - the Claude-profile alias generation in `~/.local/bin`
 
-Bugs in `claude`, `codex`, `opencode`, `cursor-agent`, `pmg`, `vet`, `gryph`, `rtk`, or the upstream devcontainer base image are out of scope — report those to their respective projects.
+Bugs in `claude`, `codex`, `opencode`, `cursor-agent`, `pmg`, `vet`, `rtk`, or the upstream devcontainer base image are out of scope — report those to their respective projects.
 
 ## Supported versions
 
diff --git a/docs/claude-profiles.md b/docs/claude-profiles.md
index a21829e..d55d139 100644
--- a/docs/claude-profiles.md
+++ b/docs/claude-profiles.md
@@ -53,19 +53,25 @@ Each repo has its own `claude_home` named volume, so by default you re-login on
 
    ### Option A — macOS Keychain (recommended)
 
-   Plaintext token never touches a dotfile.
+   Plaintext token never touches a dotfile. `aidc` reads it from the Keychain on
+   demand for `aidc claude`, so **no `~/.zshrc` export is needed** — the token
+   never gets broadcast into every shell process.
 
    ```bash
-   # one-time
+   # one-time — store the token under the service aidc looks up
    security add-generic-password -U \
      -a "$USER" -s claude-code-oauth-token \
      -w 'sk-ant-oat01-...'
-
-   # in ~/.zshrc — this line references the keychain, not the secret
-   export CLAUDE_CODE_OAUTH_TOKEN="$(security find-generic-password -a "$USER" -s claude-code-oauth-token -w 2>/dev/null)"
    ```
 
-   First time a shell starts, macOS asks whether to allow `security` to read the item — click "Always Allow".
+   That's it. The first time `aidc claude` runs, macOS asks whether to allow
+   `security` to read the item — click "Always Allow".
+
+   Override the service name (or disable the lookup) with
+   `AIDC_CLAUDE_OAUTH_KEYCHAIN_SERVICE` in `~/.config/aidc/config.env`; set it
+   empty to turn the Keychain lookup off. If `CLAUDE_CODE_OAUTH_TOKEN` is already
+   in the environment it always wins, so an existing `~/.zshrc` export still
+   works unchanged.
 
    Rotate later: `security add-generic-password -U -a "$USER" -s claude-code-oauth-token -w 'NEW_TOKEN'`. Delete: `security delete-generic-password -a "$USER" -s claude-code-oauth-token`.
 
@@ -85,11 +91,16 @@ Each repo has its own `claude_home` named volume, so by default you re-login on
    [ -f ~/.config/aidc/secrets.env ] && source ~/.config/aidc/secrets.env
    ```
 
-3. Re-open your terminal (or `source ~/.zshrc`). `aidc claude` now forwards `CLAUDE_CODE_OAUTH_TOKEN` into the container, and Claude Code uses it directly — no per-repo login.
+3. With Option A you're done — `aidc claude` resolves the token from the Keychain
+   each run and Claude Code uses it directly, no per-repo login. With Option B,
+   re-open your terminal (or `source ~/.zshrc`) so the export is in your shell;
+   `aidc claude` then forwards it into the container.
 
-Verify:
+Verify (Keychain path — the token is intentionally *not* in your shell):
 ```bash
-[ -n "$CLAUDE_CODE_OAUTH_TOKEN" ] && echo "set" || echo "MISSING"
+# Option A: confirm the Keychain item exists; aidc reads it on demand.
+security find-generic-password -a "$USER" -s claude-code-oauth-token -w | head -c 12 && echo "..."
+# The token reaches the container even though your shell never exported it:
 aidc exec -- printenv CLAUDE_CODE_OAUTH_TOKEN | head -c 12 && echo "..."
 ```
 
diff --git a/docs/install.md b/docs/install.md
index 3af50f5..c872ecf 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -102,7 +102,7 @@ sudo apt-get install -y --no-install-recommends golang-go
 go install golang.org/x/tools/gopls@latest
 ```
 
-Runs as `vscode` at image build time, with passwordless `sudo` available for system packages. The `COPY` is the last layer in the Dockerfile, so edits invalidate **only** the project-setup layer — the heavy base layers (apt, uv/Python, native agent binaries, pmg/vet/gryph/rtk) stay cached.
+Runs as `vscode` at image build time, with passwordless `sudo` available for system packages. The `COPY` is the last layer in the Dockerfile, so edits invalidate **only** the project-setup layer — the heavy base layers (apt, uv/Python, native agent binaries, pmg/vet/rtk) stay cached.
 
 After editing, `aidc rebuild` (or just `aidc up` — `--build` is implicit) picks up the change.
 
diff --git a/docs/security.md b/docs/security.md
index 76eed8f..582e018 100644
--- a/docs/security.md
+++ b/docs/security.md
@@ -80,18 +80,51 @@ the same host credentials. For xAI specifically, either log in interactively
 (persisted in `~/.grok`) or export the xAI key on the host and add it to the
 passthrough list in `AIDC_PASSTHROUGH_ENV_KEYS` (`lib/aidc.sh`) before launching.
 
-## Agent guardrails: gryph + rtk
+Only env vars actually set in `aidc`'s own process are forwarded — the value is
+read at exec time and lives only for the duration of that `docker compose exec`,
+never written into the container image or compose file.
 
-The image also ships [`gryph`](https://github.com/safedep/gryph) (SafeDep's agent security layer — patches hook entries into the detected agents' settings) and [`rtk`](https://github.com/rtk-ai/rtk) (Rust Token Killer — token-saving CLI proxy that rewrites commands like `git status` → `rtk git status` via the Claude Code hook).
+**Narrowing the passthrough per container.** `AIDC_PASSTHROUGH_ENV_KEYS` is a
+plain shell array sourced *before* it is consumed, so a host-wide
+`~/.config/aidc/config.env` or a single repo's `.ai-container/project.env` can
+reassign it to forward fewer keys (or none) into that container:
 
-Both are auto-initialised the first time a fresh `claude_home` volume is created: `bootstrap-state.sh init` runs `gryph install` and `rtk init --global`, then drops a marker at `~/.claude/.aidc-agent-hooks-installed` so it's not rerun on every container restart. `aidc destroy -f` wipes the volume and the marker, so the next `aidc up` re-applies hooks cleanly.
+```bash
+# .ai-container/project.env — forward nothing into THIS container
+AIDC_PASSTHROUGH_ENV_KEYS=()
+
+# …or a narrowed subset (drop the Claude OAuth token here)
+AIDC_PASSTHROUGH_ENV_KEYS=("OPENAI_API_KEY")
+```
+
+This also gates the Keychain lookup below — dropping `CLAUDE_CODE_OAUTH_TOKEN`
+from the array disables resolving it for that container. The one exception is the
+`aidc claude` one-time-login bootstrap (`aidc-bootstrap-claude`), which reads
+`CLAUDE_CODE_OAUTH_TOKEN` directly when it is already present.
+
+**On-demand Claude OAuth token (macOS Keychain).** For `aidc claude`, if
+`CLAUDE_CODE_OAUTH_TOKEN` is not already in the environment, `aidc` reads it from
+the macOS Keychain on demand (service `claude-code-oauth-token`, your `$USER`
+account) so the token never has to be exported into every shell via `~/.zshrc`.
+Override the service name or disable the lookup with
+`AIDC_CLAUDE_OAUTH_KEYCHAIN_SERVICE` (set it empty to disable). The lookup is a
+no-op on hosts without the `security` tool. See `docs/claude-profiles.md` for
+setup.
+
+## Agent guardrails: rtk
+
+The image ships [`rtk`](https://github.com/rtk-ai/rtk) (Rust Token Killer — a token-saving CLI proxy that rewrites commands like `git status` → `rtk git status` via the Claude Code `PreToolUse`/`Bash` hook, typically cutting 60–90% of the tokens dev operations cost).
+
+rtk is auto-initialised the first time a fresh `claude_home` volume is created: `bootstrap-state.sh init` runs `rtk init --global --auto-patch --hook-only` (non-interactive; installs just the hook, no `RTK.md`/`CLAUDE.md` rewrite since both are seeded from the host), then drops a marker at `~/.claude/.aidc-agent-hooks-installed` so it isn't rerun on every container restart. `aidc destroy -f` wipes the volume and the marker, so the next `aidc up` re-applies the hook cleanly.
+
+The host's own agent hooks — SafeDep's `gryph` audit layer, and `cot` (whose command is a macOS-only binary path) — are host-side concerns: in-container transcripts auto-sync back to the host on container start and exit, so observability happens there rather than in the VM. `bootstrap-state.sh` strips those host-only hook entries from the seeded `settings.json` on every sync (preserving rtk and any user hooks), so the VM never carries hooks that can't run inside it.
 
 Verify:
 
 ```bash
-aidc exec -- gryph status
 aidc exec -- rtk --version
-aidc exec -- cat /home/vscode/.claude/settings.json | jq '.hooks // {}'   # hook entries from both
+aidc exec -- rtk gain                                                     # token savings so far
+aidc exec -- cat /home/vscode/.claude/settings.json | jq '.hooks // {}'   # just the rtk PreToolUse/Bash hook
 ```
 
 ## Optional: egress firewall
diff --git a/lib/aidc.sh b/lib/aidc.sh
index 1103e39..c526fd5 100644
--- a/lib/aidc.sh
+++ b/lib/aidc.sh
@@ -9,10 +9,15 @@ AIDC_VERSION="${AIDC_VERSION:-0.1.0}"
 AIDC_CONTAINER_USER="${AIDC_CONTAINER_USER:-vscode}"
 AIDC_CONTAINER_HOME="${AIDC_CONTAINER_HOME:-/home/vscode}"
 AIDC_HOST_CONFIG_ROOT="${AIDC_HOST_CONFIG_ROOT:-$HOME/.config/aidc}"
+AIDC_GLOBAL_CONFIG="${AIDC_GLOBAL_CONFIG:-$AIDC_HOST_CONFIG_ROOT/config.env}"
 AIDC_EMPTY_ROOT="${AIDC_EMPTY_ROOT:-$AIDC_HOST_CONFIG_ROOT/empty}"
 AIDC_PROVIDER_ROOT="${AIDC_PROVIDER_ROOT:-$AIDC_HOST_CONFIG_ROOT/providers/claude}"
 AIDC_CLAUDE_PROFILE_ROOT="${AIDC_CLAUDE_PROFILE_ROOT:-$AIDC_PROVIDER_ROOT}"
 AIDC_BIN_DIR="${AIDC_BIN_DIR:-${AIDC_INSTALL_DIR:-$HOME/.local/bin}}"
+# macOS Keychain service that holds the Claude OAuth token. When set (the
+# default), aidc reads the token from the Keychain on demand instead of
+# requiring it to be exported into every shell. Set empty to disable.
+AIDC_CLAUDE_OAUTH_KEYCHAIN_SERVICE="${AIDC_CLAUDE_OAUTH_KEYCHAIN_SERVICE:-claude-code-oauth-token}"
 AIDC_CORE_ROOT_DEFAULT="${AIDC_CORE_ROOT_DEFAULT:-$HOME/CORE_LOGICS}"
 AIDC_CORE_WORKTREE_ROOT="${AIDC_CORE_WORKTREE_ROOT:-$HOME/.local/share/aidc/core-worktrees}"
 AIDC_MANAGED_CLAUDE_ALIAS_MARKER="# aidc-managed claude-alias"
@@ -60,6 +65,9 @@ aidc::main() {
     rebuild)
       aidc::cmd_rebuild "$@"
       ;;
+    rescan)
+      aidc::cmd_rescan "$@"
+      ;;
     status)
       aidc::cmd_status "$@"
       ;;
@@ -117,6 +125,7 @@ Usage:
   aidc up [--clipboard] [--isolate-vm]
   aidc down
   aidc rebuild [--clipboard] [--isolate-vm]
+  aidc rescan
   aidc status [--global]
   aidc destroy [-f] [--purge-worktree] [--purge-scaffold]
   aidc shell
@@ -138,8 +147,12 @@ Notes:
   - aidc cursor opens the host Cursor app; reopen the repo in the devcontainer.
   - aidc destroy removes the container, named volumes, and image by default.
     Worktree and scaffold removal are opt-in via the listed flags.
+  - aidc rescan re-detects project languages (handy once a repo that started
+    empty gains code) and rebuilds so the matching toolchains/scanners install.
   - aidc sync-sessions pulls in-container session logs back to host
-    ~/.claude/projects so '/insights' on the host can see them.
+    ~/.claude/projects so '/insights' on the host can see them. Sessions also
+    auto-sync on container start, agent exit, 'down', and 'destroy' unless
+    AIDC_AUTO_SYNC_SESSIONS=0.
   - The host-clipboard bridge is off by default. Enable it at (re)create time
     with 'aidc up --clipboard' or 'aidc rebuild --clipboard'.
   - Per-project VM isolation is off by default due to resource cost. Enable it
@@ -197,6 +210,12 @@ aidc::refresh_scaffold() {
   aidc::copy_template "templates/devcontainer/scripts/init-firewall.sh.tmpl" "$workspace/.devcontainer/scripts/init-firewall.sh" "0755"
   # User-owned. Created once, never refreshed; edits drive per-project image layers.
   aidc::copy_template_once "templates/devcontainer/project-setup.sh.tmpl" "$workspace/.devcontainer/project-setup.sh" "0755"
+  # Project documentation seeds. Created once and never overwritten so the
+  # project's own history is never clobbered. Intentionally NOT git-excluded —
+  # these belong to the repo and should be committed.
+  aidc::copy_template_once "templates/CHANGELOG.md.tmpl" "$workspace/CHANGELOG.md" "0644"
+  aidc::copy_template_once "templates/DETAILED_CHANGELOG.md.tmpl" "$workspace/DETAILED_CHANGELOG.md" "0644"
+  aidc::copy_template_once "templates/logs/README.md.tmpl" "$workspace/logs/README.md" "0644"
   aidc::merge_template "templates/CLAUDE.md.tmpl" "$workspace/CLAUDE.md"
   aidc::merge_template "templates/AGENTS.md.tmpl" "$workspace/AGENTS.md"
   aidc::copy_template "templates/cursor-rules/00-core-logics.mdc.tmpl" "$workspace/.cursor/rules/00-core-logics.mdc" "0644"
@@ -219,6 +238,9 @@ aidc::cmd_up() {
   fi
 
   aidc::compose "$workspace" up -d --build workspace
+  # Catch up the host with any transcripts a prior (possibly ungraceful) session
+  # left in the volume — the recovery case the on-exit hooks can't cover.
+  aidc::auto_sync_sessions "$workspace" all
   aidc::log "container is ready for $(basename "$workspace")"
 }
 
@@ -233,9 +255,37 @@ aidc::cmd_rebuild() {
   fi
 
   aidc::compose "$workspace" up -d --build --force-recreate workspace
+  aidc::auto_sync_sessions "$workspace" all
   aidc::log "container rebuilt for $(basename "$workspace")"
 }
 
+# Re-detect project languages and rebuild so newly-applicable toolchains and
+# their security scanners get installed. Useful when a repo that started empty
+# (or single-language) later gains code aidc didn't see at first build.
+aidc::cmd_rescan() {
+  local workspace
+  workspace="$(aidc::default_workspace)"
+  aidc::ensure_workspace_ready "$workspace"
+
+  local detected effective
+  detected="$(aidc::detect_toolchains "$workspace")"
+  effective="$(aidc::compute_toolchains "$workspace")"
+
+  aidc::log "detected toolchains: ${detected:-none}"
+  if [[ "$effective" != "$detected" ]]; then
+    # project.env pins AIDC_TOOLCHAINS, so detection is informational only.
+    aidc::log "effective toolchains (AIDC_TOOLCHAINS override): ${effective:-none}"
+  fi
+
+  if [[ "${AIDC_ISOLATE_VM:-0}" == "1" ]]; then
+    aidc::vm_ensure "$workspace"
+  fi
+
+  # --build picks up the changed AIDC_TOOLCHAINS build arg and reinstalls.
+  aidc::compose "$workspace" up -d --build workspace
+  aidc::log "rescan complete for $(basename "$workspace")"
+}
+
 # Parse flags shared by 'up' and 'rebuild'.
 # --clipboard: opt-in host-clipboard bridge. Off by default; can also be
 #   persisted as AIDC_ENABLE_CLIPBOARD=1 in .ai-container/project.env.
@@ -260,6 +310,8 @@ aidc::cmd_down() {
     aidc::die "no aidc project in $workspace (run 'aidc init' first)"
   fi
   aidc::load_project_env "$workspace"
+  # Pull session transcripts to the host while the container is still up.
+  aidc::auto_sync_sessions "$workspace" all
   aidc::compose "$workspace" down
 
   if [[ "${AIDC_ISOLATE_VM:-0}" == "1" ]]; then
@@ -549,6 +601,8 @@ aidc::cmd_destroy() {
     esac
   fi
 
+  # Last chance to pull session transcripts before '-v' wipes the volumes.
+  aidc::auto_sync_sessions "$workspace" all
   aidc::compose "$workspace" down -v --rmi local --remove-orphans
 
   if [[ "${AIDC_ISOLATE_VM:-0}" == "1" ]]; then
@@ -787,6 +841,37 @@ aidc::sync_session_tool() {
   aidc::log "synced $tool sessions to $host_dst"
 }
 
+# Best-effort session sync wired into the agent/lifecycle paths so transcripts
+# land on the host without a manual 'aidc sync-sessions'. Opt out by setting
+# AIDC_AUTO_SYNC_SESSIONS=0 in .ai-container/project.env. 'tool' is a single
+# tool name or 'all'; tools without a session mapping (e.g. cursor-agent) are
+# skipped. Never aborts the caller — sync failures are logged, not fatal.
+aidc::auto_sync_sessions() {
+  local workspace="$1"
+  local tool="$2"
+  [[ "${AIDC_AUTO_SYNC_SESSIONS:-1}" == "0" ]] && return 0
+
+  # No container, nothing to pull (e.g. auto-sync after a failed start).
+  [[ -n "$(aidc::compose_capture "$workspace" ps -q workspace 2>/dev/null)" ]] || return 0
+
+  if [[ "$tool" == "all" ]]; then
+    local t
+    for t in claude codex opencode grok; do
+      aidc::sync_session_tool "$workspace" "$t" || true
+    done
+    return 0
+  fi
+
+  case "$tool" in
+    claude|codex|opencode|grok)
+      aidc::sync_session_tool "$workspace" "$tool" || true
+      ;;
+    *)
+      # cursor-agent and unknowns have no session volume to sync.
+      ;;
+  esac
+}
+
 aidc::run_tool() {
   local tool="$1"
   local profile="$2"
@@ -796,6 +881,10 @@ aidc::run_tool() {
   workspace="$(aidc::default_workspace)"
   aidc::ensure_container_running "$workspace"
 
+  if [[ "$tool" == "claude" ]]; then
+    aidc::resolve_claude_oauth_token
+  fi
+
   AIDC_EXEC_ENV_ARGS=()
   aidc::append_passthrough_env_args
   if [[ "$tool" == "claude" && -n "$profile" ]]; then
@@ -836,7 +925,12 @@ aidc::run_tool() {
     command+=("$@")
   fi
 
-  aidc::compose_exec "$workspace" "${command[@]}"
+  # Run the agent in the foreground; once it exits, pull its session transcripts
+  # back to the host. Preserve the agent's exit code as our own.
+  local rc=0
+  aidc::compose_exec "$workspace" "${command[@]}" || rc=$?
+  aidc::auto_sync_sessions "$workspace" "$tool"
+  return "$rc"
 }
 
 aidc::need_cmd() {
@@ -1358,6 +1452,12 @@ AIDC_REPO_SLUG=$repo_slug
 AIDC_CORE_ROOT=$(aidc::shell_escape "$core_root")
 AIDC_CORE_BRANCH=$core_branch
 AIDC_CORE_WORKTREE=$(aidc::shell_escape "$core_worktree")
+
+# Auto-pull in-container agent transcripts to the host on container start, agent
+# exit, 'down', and 'destroy'. Set to 0 to disable and sync manually with
+# 'aidc sync-sessions'. Overrides the host-wide default in
+# ~/.config/aidc/config.env for this project only.
+# AIDC_AUTO_SYNC_SESSIONS=1
 EOF
 }
 
@@ -1430,13 +1530,28 @@ aidc::ensure_container_running() {
 
   if [[ -z "$(aidc::compose_capture "$workspace" ps -q workspace)" ]]; then
     aidc::compose "$workspace" up -d --build workspace
+    # Only on the down→up transition (not every exec), so we recover prior
+    # transcripts without adding a sync to each command.
+    aidc::auto_sync_sessions "$workspace" all
   fi
 }
 
+# Source host-wide aidc defaults (~/.config/aidc/config.env) if present. These
+# are universal settings shared by every project on this host. A project's
+# .ai-container/project.env is sourced afterwards and overrides them, so a
+# per-folder setting always wins over the global default.
+aidc::load_global_config() {
+  [[ -f "$AIDC_GLOBAL_CONFIG" ]] || return 0
+  # shellcheck disable=SC1090
+  . "$AIDC_GLOBAL_CONFIG"
+}
+
 aidc::load_project_env() {
   local workspace="$1"
   local env_file="$workspace/.ai-container/project.env"
   [[ -f "$env_file" ]] || aidc::die "missing project env: $env_file"
+  # Global defaults first; per-folder project.env overrides them.
+  aidc::load_global_config
   # shellcheck disable=SC1090
   . "$env_file"
 }
@@ -1532,6 +1647,31 @@ aidc::ensure_host_config_dirs() {
   mkdir -p "$AIDC_HOST_CONFIG_ROOT" "$AIDC_EMPTY_ROOT" "$AIDC_CLAUDE_PROFILE_ROOT"
   mkdir -p "$AIDC_EMPTY_ROOT/claude" "$AIDC_EMPTY_ROOT/codex" "$AIDC_EMPTY_ROOT/opencode" "$AIDC_EMPTY_ROOT/grok" "$AIDC_EMPTY_ROOT/clipboard"
   touch "$AIDC_EMPTY_ROOT/gitconfig"
+  aidc::ensure_global_config
+}
+
+# Seed the host-wide config file once, fully commented so sourcing it is a no-op
+# until the user edits it. Lists the settings that make sense as global defaults.
+aidc::ensure_global_config() {
+  [[ -f "$AIDC_GLOBAL_CONFIG" ]] && return 0
+  mkdir -p "$(dirname "$AIDC_GLOBAL_CONFIG")"
+  cat >"$AIDC_GLOBAL_CONFIG" <<'EOF'
+# aidc global config — universal defaults for every project on this host.
+# A project's .ai-container/project.env is sourced AFTER this file and overrides
+# anything set here, so per-folder settings win. Uncomment a line to change a
+# host-wide default.
+
+# Auto-pull in-container agent transcripts to the host on container start, agent
+# exit, 'down', and 'destroy'. Set to 0 to disable everywhere by default.
+# AIDC_AUTO_SYNC_SESSIONS=1
+
+# macOS Keychain service holding the Claude OAuth token. aidc reads it on demand
+# for 'aidc claude' (no need to export CLAUDE_CODE_OAUTH_TOKEN in your shell).
+# Store the token once with:
+#   security add-generic-password -U -a "$USER" -s claude-code-oauth-token -w 'sk-ant-oat01-...'
+# Override the service name below, or set it empty to disable the lookup.
+# AIDC_CLAUDE_OAUTH_KEYCHAIN_SERVICE=claude-code-oauth-token
+EOF
 }
 
 aidc::ensure_claude_profile_examples() {
@@ -1672,6 +1812,33 @@ aidc::export_compose_env() {
   fi
 }
 
+# True when the workspace contains shell scripts worth linting with shellcheck.
+# Fast path is the name-based '*.sh' check; the shebang probe is bounded to
+# executable, extensionless files (capped) so big repos stay cheap. Uses only
+# POSIX find/head so it works with macOS (BSD) find under bash 3.2.
+aidc::has_shell_scripts() {
+  local workspace="$1"
+
+  # Fast path: any *.sh file, skipping VCS/vendor dirs.
+  if [[ -n "$(find "$workspace" \
+        \( -type d \( -name .git -o -name node_modules -o -name vendor \) -prune \) -o \
+        \( -type f -name '*.sh' -print \) 2>/dev/null | head -n1)" ]]; then
+    return 0
+  fi
+
+  # Extensionless executables with a shell shebang (e.g. bin/aidc).
+  local f first
+  while IFS= read -r f; do
+    [[ -n "$f" ]] || continue
+    first="$(head -n1 "$f" 2>/dev/null)"
+    [[ "$first" == '#!'*sh* ]] && return 0
+  done < <(find "$workspace" \
+        \( -type d \( -name .git -o -name node_modules -o -name vendor \) -prune \) -o \
+        \( -type f -perm -u+x ! -name '*.*' -print \) 2>/dev/null | head -n 200)
+
+  return 1
+}
+
 aidc::detect_toolchains() {
   local workspace="$1"
   local -a detected=()
@@ -1690,6 +1857,12 @@ aidc::detect_toolchains() {
   if [[ -f "$workspace/requirements.txt" || -f "$workspace/uv.lock" || -f "$workspace/pyproject.toml" || -f "$workspace/Pipfile" || -f "$workspace/Pipfile.lock" || -f "$workspace/poetry.lock" ]]; then
     detected+=("python")
   fi
+  # Shell has no manifest file, so detect it from content: any *.sh file or an
+  # extensionless executable with a shell shebang (e.g. bin/aidc). The 'shell'
+  # toolchain arm installs the shellcheck linter.
+  if aidc::has_shell_scripts "$workspace"; then
+    detected+=("shell")
+  fi
   # Join with commas without touching the global IFS.
   local out="" item
   for item in ${detected[@]+"${detected[@]}"}; do
@@ -1742,6 +1915,35 @@ aidc::append_passthrough_env_args() {
   done
 }
 
+# Populate CLAUDE_CODE_OAUTH_TOKEN from the macOS Keychain so the token only
+# lives in this process for the duration of the exec, instead of being exported
+# into every shell via ~/.zshrc. No-op when the token is already set, when the
+# key has been dropped from the passthrough list (per-project opt-out via
+# AIDC_PASSTHROUGH_ENV_KEYS), when the Keychain lookup is disabled, or when the
+# `security` tool is unavailable (e.g. non-macOS hosts). Never logs the token.
+aidc::resolve_claude_oauth_token() {
+  [[ -n "${CLAUDE_CODE_OAUTH_TOKEN:-}" ]] && return 0
+  [[ -n "${AIDC_CLAUDE_OAUTH_KEYCHAIN_SERVICE:-}" ]] || return 0
+
+  local key forwarded=0
+  for key in "${AIDC_PASSTHROUGH_ENV_KEYS[@]}"; do
+    if [[ "$key" == "CLAUDE_CODE_OAUTH_TOKEN" ]]; then
+      forwarded=1
+      break
+    fi
+  done
+  [[ "$forwarded" -eq 1 ]] || return 0
+
+  command -v security >/dev/null 2>&1 || return 0
+
+  local account token
+  account="${USER:-$(id -un 2>/dev/null || true)}"
+  token="$(security find-generic-password -a "$account" -s "$AIDC_CLAUDE_OAUTH_KEYCHAIN_SERVICE" -w 2>/dev/null || true)"
+  if [[ -n "$token" ]]; then
+    export CLAUDE_CODE_OAUTH_TOKEN="$token"
+  fi
+}
+
 aidc::validate_claude_profile_name() {
   local profile="$1"
   [[ "$profile" =~ ^[a-z0-9][a-z0-9-]*$ ]] || aidc::die "invalid Claude profile name: $profile"
diff --git a/templates/AGENTS.md.tmpl b/templates/AGENTS.md.tmpl
index 506b7e4..62bbebd 100644
--- a/templates/AGENTS.md.tmpl
+++ b/templates/AGENTS.md.tmpl
@@ -20,7 +20,37 @@ All scanners are pre-installed in the aidc container.
 - **Rust** (when `Cargo.toml` present): `cargo audit`
 - **Ruby** (when `Gemfile` present): `bundle-audit check --update`
 - **Node** (when `package.json` present): `npm audit --omit=dev` (or `pnpm audit` / `yarn npm audit`).
+- **Shell** (when shell scripts present): `shellcheck <files>` on changed `*.sh` and shebang scripts.
 - **Dependency vetting** (any language): `vet scan -D .` for SCA against the OSV database.
 
 When findings exist, the work is not done. Fix them, re-run the scan, and only then report the task as complete.
+
+## Testing & coverage
+
+Every code change ships with tests. Aim for full coverage of the lines you add or change — cover the happy path, edge cases, and error handling, not just the obvious case. If a line is genuinely untestable, say why in the change.
+
+Run the project's coverage tool and confirm the changed code is exercised before declaring work complete:
+
+- **Go**: `go test -cover ./...`
+- **Python**: `pytest --cov` (`coverage run -m pytest` + `coverage report`)
+- **Rust**: `cargo llvm-cov` (or `cargo tarpaulin`)
+- **Node**: `npm test -- --coverage` (`jest --coverage` / `vitest run --coverage`)
+- **Ruby**: SimpleCov via `bundle exec rspec`
+
+Coverage tools that aren't pre-installed can be added per project in `.devcontainer/project-setup.sh`.
+
+## Documentation & changelog
+
+Every meaningful change updates **both** changelog files:
+
+- `CHANGELOG.md` — one high-level bullet under the right heading, in [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
+- `DETAILED_CHANGELOG.md` — a dated long-form entry (what / why / how / commands / verification / notes), newest first.
+
+## Documentation requirements
+
+**Meticulously document all activities performed in this project.** Every action — commands run, configuration changed, files transferred, troubleshooting steps, observations — gets recorded: the exact commands and their output, the reasoning behind each action, any errors and how they were resolved, and the design choices made. Treat every session as something that may need to be audited, reproduced, or rolled back. If it was done, write it down.
+
+## Session log convention
+
+Every working session writes a log to `logs/YYYY-MM-DD-<slug>.md` (date is the session date, slug is a short kebab-case description of the change). Existing entries are the template — match their structure: symptom → diagnosis → change (with diff) → commands → verification → notes. See `logs/README.md`.
 <!-- aidc:core-logics:end -->
diff --git a/templates/CHANGELOG.md.tmpl b/templates/CHANGELOG.md.tmpl
new file mode 100644
index 0000000..cfc3ab6
--- /dev/null
+++ b/templates/CHANGELOG.md.tmpl
@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Keep this file high-level: one bullet per user-visible change, grouped under the
+right heading. Record the blow-by-blow detail (commands, diffs, reasoning) in
+`DETAILED_CHANGELOG.md` instead.
+
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security
diff --git a/templates/CLAUDE.md.tmpl b/templates/CLAUDE.md.tmpl
index 9b633e3..e56eccc 100644
--- a/templates/CLAUDE.md.tmpl
+++ b/templates/CLAUDE.md.tmpl
@@ -20,7 +20,37 @@ All scanners are pre-installed in the aidc container.
 - **Rust** (when `Cargo.toml` present): `cargo audit`
 - **Ruby** (when `Gemfile` present): `bundle-audit check --update`
 - **Node** (when `package.json` present): `npm audit --omit=dev` (or `pnpm audit` / `yarn npm audit`).
+- **Shell** (when shell scripts present): `shellcheck <files>` on changed `*.sh` and shebang scripts.
 - **Dependency vetting** (any language): `vet scan -D .` for SCA against the OSV database.
 
 When findings exist, the work is not done. Fix them, re-run the scan, and only then report the task as complete.
+
+## Testing & coverage
+
+Every code change ships with tests. Aim for full coverage of the lines you add or change — cover the happy path, edge cases, and error handling, not just the obvious case. If a line is genuinely untestable, say why in the change.
+
+Run the project's coverage tool and confirm the changed code is exercised before declaring work complete:
+
+- **Go**: `go test -cover ./...`
+- **Python**: `pytest --cov` (`coverage run -m pytest` + `coverage report`)
+- **Rust**: `cargo llvm-cov` (or `cargo tarpaulin`)
+- **Node**: `npm test -- --coverage` (`jest --coverage` / `vitest run --coverage`)
+- **Ruby**: SimpleCov via `bundle exec rspec`
+
+Coverage tools that aren't pre-installed can be added per project in `.devcontainer/project-setup.sh`.
+
+## Documentation & changelog
+
+Every meaningful change updates **both** changelog files:
+
+- `CHANGELOG.md` — one high-level bullet under the right heading, in [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
+- `DETAILED_CHANGELOG.md` — a dated long-form entry (what / why / how / commands / verification / notes), newest first.
+
+## Documentation requirements
+
+**Meticulously document all activities performed in this project.** Every action — commands run, configuration changed, files transferred, troubleshooting steps, observations — gets recorded: the exact commands and their output, the reasoning behind each action, any errors and how they were resolved, and the design choices made. Treat every session as something that may need to be audited, reproduced, or rolled back. If it was done, write it down.
+
+## Session log convention
+
+Every working session writes a log to `logs/YYYY-MM-DD-<slug>.md` (date is the session date, slug is a short kebab-case description of the change). Existing entries are the template — match their structure: symptom → diagnosis → change (with diff) → commands → verification → notes. See `logs/README.md`.
 <!-- aidc:core-logics:end -->
diff --git a/templates/DETAILED_CHANGELOG.md.tmpl b/templates/DETAILED_CHANGELOG.md.tmpl
new file mode 100644
index 0000000..b4e3efe
--- /dev/null
+++ b/templates/DETAILED_CHANGELOG.md.tmpl
@@ -0,0 +1,33 @@
+# Detailed Changelog
+
+The long-form companion to `CHANGELOG.md`. Where `CHANGELOG.md` says *what*
+changed in one line, this file records *why* and *how* — enough for a future
+reader to audit, reproduce, or roll back any change without re-deriving it.
+
+Add a new entry (newest first) for every meaningful change. Use the template
+below; drop sections that genuinely don't apply.
+
+---
+
+## YYYY-MM-DD — <short title>
+
+**Summary:** One or two sentences on what changed and the user-facing effect.
+
+**Why:** The problem, request, or constraint that prompted this. Link the issue
+/ ticket / discussion if there is one.
+
+**What changed:**
+- File-by-file or component-by-component list of the edits.
+
+**How / commands run:**
+```
+# exact commands executed, with the relevant output
+```
+
+**Errors encountered & resolution:** Anything that went wrong and how it was
+fixed (or why it was left as-is).
+
+**Verification:** How the change was proven to work — tests run, scanners,
+manual checks, screenshots.
+
+**Notes / follow-ups:** Design choices, trade-offs, and anything deferred.
diff --git a/templates/devcontainer/Dockerfile.tmpl b/templates/devcontainer/Dockerfile.tmpl
index c47f458..bae5a6f 100644
--- a/templates/devcontainer/Dockerfile.tmpl
+++ b/templates/devcontainer/Dockerfile.tmpl
@@ -99,9 +99,6 @@ RUN ARCH_RAW="$(dpkg --print-architecture)" \
     && chmod 0755 /usr/local/bin/vet \
     && rm /tmp/vet.tar.gz
 
-# Agent security/observability layer for Claude Code, Codex, OpenCode, Cursor.
-RUN curl -fsSL https://raw.githubusercontent.com/safedep/gryph/main/install.sh | sh
-
 # Always-on security tooling: semgrep (SAST), gitleaks + trufflehog (secrets).
 # SCA is handled by vet/pmg above; this layer covers code-pattern and secret scans.
 RUN uv tool install semgrep \
@@ -249,6 +246,9 @@ RUN if [ -n "$AIDC_TOOLCHAINS" ]; then \
           php) \
             sudo apt-get update && \
             sudo apt-get install -y --no-install-recommends php-cli ;; \
+          shell) \
+            sudo apt-get update && \
+            sudo apt-get install -y --no-install-recommends shellcheck ;; \
           node) \
             echo "aidc: node 22 already in base (npm/pnpm/yarn/bun via pmg shims; npm audit built-in)" ;; \
           python) \
diff --git a/templates/devcontainer/scripts/bootstrap-state.sh.tmpl b/templates/devcontainer/scripts/bootstrap-state.sh.tmpl
index 1005809..41f039d 100644
--- a/templates/devcontainer/scripts/bootstrap-state.sh.tmpl
+++ b/templates/devcontainer/scripts/bootstrap-state.sh.tmpl
@@ -45,10 +45,66 @@ copy_dir_from_seed() {
   rsync -a --delete "$source"/ "$target"/
 }
 
+# Remove hook entries that reference host-only tooling from a Claude Code
+# settings.json: `gryph` (agent audit layer — handled on the host now that
+# sessions auto-sync) and `cot` (whose command is a hard-coded macOS binary
+# path that can never resolve inside the VM). Surgical and idempotent: rtk's
+# PreToolUse/Bash hook and any user hooks are preserved; only matching commands
+# are dropped, then emptied hook arrays and emptied event keys are pruned. The
+# file is left untouched when nothing matches. Safe to run on every init, which
+# also self-heals settings.json on volumes seeded by an older bootstrap.
+strip_host_hooks() {
+  local f="$1"
+  [[ -f "$f" ]] || return 0
+  command -v python3 >/dev/null 2>&1 || return 0
+  python3 - "$f" <<'PY'
+import json, re, sys
+p = sys.argv[1]
+try:
+    cfg = json.load(open(p))
+except (FileNotFoundError, ValueError):
+    sys.exit(0)
+hooks = cfg.get("hooks")
+if not isinstance(hooks, dict):
+    sys.exit(0)
+bad = re.compile(r"\bgryph\b|\bcot\b")
+changed = False
+for event in list(hooks):
+    entries = hooks[event]
+    if not isinstance(entries, list):
+        continue
+    kept_entries = []
+    for entry in entries:
+        cmds = entry.get("hooks") if isinstance(entry, dict) else None
+        if not isinstance(cmds, list):
+            kept_entries.append(entry)
+            continue
+        kept = [c for c in cmds if not bad.search(c.get("command", ""))]
+        if len(kept) != len(cmds):
+            changed = True
+        if kept:
+            entry["hooks"] = kept
+            kept_entries.append(entry)
+    if kept_entries:
+        hooks[event] = kept_entries
+    else:
+        del hooks[event]
+        changed = True
+if changed:
+    with open(p, "w") as fh:
+        json.dump(cfg, fh, indent=2)
+        fh.write("\n")
+PY
+}
+
 sync_claude() {
   ensure_dir "$home_dir/.claude"
   copy_file_from_seed "/host-seed/claude/settings.json" "$home_dir/.claude/settings.json" "0600"
   copy_file_from_seed "/host-seed/claude/CLAUDE.md" "$home_dir/.claude/CLAUDE.md" "0644"
+  # The host seed's settings.json carries hooks for host-only tools (gryph, cot);
+  # they're pointless in the VM and cot would error on every fire. Strip just
+  # those — rtk installs its own hook below and any user hooks are preserved.
+  strip_host_hooks "$home_dir/.claude/settings.json"
 }
 
 sync_codex() {
@@ -90,11 +146,13 @@ install_agent_hooks() {
   local marker="$home_dir/.claude/.aidc-agent-hooks-installed"
   [[ -f "$marker" ]] && return 0
 
-  if command -v gryph >/dev/null 2>&1; then
-    gryph install >/dev/null 2>&1 || echo "[bootstrap] gryph install failed" >&2
-  fi
+  # rtk is the only agent hook wired inside the VM. gryph/cot run on the host
+  # (sessions auto-sync), so neither is installed nor hooked here. --auto-patch
+  # makes init non-interactive; --hook-only adds just the PreToolUse/Bash hook
+  # without re-writing CLAUDE.md/RTK.md (both already seeded from the host).
   if command -v rtk >/dev/null 2>&1; then
-    rtk init --global >/dev/null 2>&1 || echo "[bootstrap] rtk init --global failed" >&2
+    rtk init --global --auto-patch --hook-only >/dev/null 2>&1 \
+      || echo "[bootstrap] rtk init --global failed" >&2
   fi
 
   mkdir -p "$(dirname "$marker")"
@@ -158,20 +216,25 @@ sync_tool() {
   esac
 }
 
-case "$mode" in
-  init)
-    align_uid
-    ensure_dir "/commandhistory"
-    sync_tool "all"
-    sync_gitconfig_overlay
-    install_agent_hooks
-    run_firewall_if_enabled
-    ;;
-  sync)
-    sync_tool "$tool"
-    ;;
-  *)
-    echo "usage: bootstrap-state.sh [init|sync] [claude|codex|opencode|grok|all]" >&2
-    exit 1
-    ;;
-esac
+# Only run the dispatch when executed directly, not when sourced (e.g. by unit
+# tests exercising strip_host_hooks()). This keeps the helper functions above
+# importable without triggering the init/sync side effects.
+if [[ "${BASH_SOURCE[0]:-}" == "${0:-}" ]]; then
+  case "$mode" in
+    init)
+      align_uid
+      ensure_dir "/commandhistory"
+      sync_tool "all"
+      sync_gitconfig_overlay
+      install_agent_hooks
+      run_firewall_if_enabled
+      ;;
+    sync)
+      sync_tool "$tool"
+      ;;
+    *)
+      echo "usage: bootstrap-state.sh [init|sync] [claude|codex|opencode|grok|all]" >&2
+      exit 1
+      ;;
+  esac
+fi
diff --git a/templates/logs/README.md.tmpl b/templates/logs/README.md.tmpl
new file mode 100644
index 0000000..6b13308
--- /dev/null
+++ b/templates/logs/README.md.tmpl
@@ -0,0 +1,28 @@
+# Session logs
+
+Every working session writes a log here so the project stays auditable,
+reproducible, and rollback-friendly.
+
+## Convention
+
+One file per session: `logs/YYYY-MM-DD-<slug>.md`
+
+- `YYYY-MM-DD` — the session date.
+- `<slug>` — a short kebab-case description of the change (e.g.
+  `fix-login-redirect`, `add-rescan-command`).
+
+Existing entries are the template — match their structure:
+
+1. **Symptom / goal** — what prompted the session.
+2. **Diagnosis** — what was investigated and found.
+3. **Change** — what was done, with the diff or key edits.
+4. **Commands** — exact commands run and their output/result.
+5. **Verification** — how the change was confirmed (tests, scanners, manual).
+6. **Notes** — reasoning, design choices, errors hit, and follow-ups.
+
+## What to record
+
+Document all activities: connections made, commands run, configuration changes,
+files transferred, troubleshooting steps, observations, the reasoning behind
+each action, errors encountered and how they were resolved, and the logical
+choices made about the design. If it was done, it should be written down.
diff --git a/tests/resolve-oauth-token.test.sh b/tests/resolve-oauth-token.test.sh
new file mode 100644
index 0000000..bf8c942
--- /dev/null
+++ b/tests/resolve-oauth-token.test.sh
@@ -0,0 +1,176 @@
+#!/usr/bin/env bash
+#
+# Unit tests for aidc::resolve_claude_oauth_token (lib/aidc.sh).
+#
+# Stubs the macOS `security` binary on PATH so the resolver can be exercised on
+# any host. Run with: bash tests/resolve-oauth-token.test.sh
+#
+# Each test case runs in its own ( ... ) subshell on purpose, so per-case PATH /
+# STUB_* exports stay isolated. shellcheck's subshell-modification warnings are
+# false positives for that pattern; SC1091 is the un-followable lib source.
+# shellcheck disable=SC1091,SC2030,SC2031
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# Obviously-fake token — never a real credential (keeps gitleaks/semgrep clean).
+FAKE_TOKEN="sk-ant-oat01-TEST-0000000000000000000000000000"
+
+# shellcheck source=../lib/aidc.sh
+. "$REPO_ROOT/lib/aidc.sh"
+
+TMP_ROOT="$(mktemp -d)"
+trap 'rm -rf "$TMP_ROOT"' EXIT
+
+STUB_DIR="$TMP_ROOT/bin"
+mkdir -p "$STUB_DIR"
+
+# Cross-subshell tallies (subshell-local variables would not propagate).
+PASSED_FILE="$TMP_ROOT/passed"
+FAILED_FILE="$TMP_ROOT/failed"
+: >"$PASSED_FILE"
+: >"$FAILED_FILE"
+
+# `security` stub. Behaviour driven by env vars so each case configures it:
+#   STUB_TOKEN  — value to print for `find-generic-password ... -w`
+#   STUB_FAIL=1 — exit non-zero with no output (item-not-found)
+#   STUB_MARKER — file the stub touches on every invocation (call detection)
+cat >"$STUB_DIR/security" <<'STUB'
+#!/usr/bin/env bash
+[[ -n "${STUB_MARKER:-}" ]] && : >"$STUB_MARKER"
+if [[ "${STUB_FAIL:-0}" == "1" ]]; then
+  exit 44
+fi
+printf '%s' "${STUB_TOKEN:-}"
+STUB
+chmod +x "$STUB_DIR/security"
+
+fail() {
+  printf 'FAIL: %s\n' "$1" >&2
+  printf '%s\n' "$1" >>"$FAILED_FILE"
+}
+ok() {
+  printf 'ok: %s\n' "$1"
+  printf '%s\n' "$1" >>"$PASSED_FILE"
+}
+
+# Run the resolver in the current shell. Captures stdout+stderr to a file (a
+# redirect, not a subshell) so any export survives for inspection. Sets
+# RESULT_TOKEN, RESULT_OUTPUT, RESULT_CALLED.
+run_resolver() {
+  local out_file="$TMP_ROOT/out"
+  local marker="$TMP_ROOT/called"
+  rm -f "$marker"
+  unset CLAUDE_CODE_OAUTH_TOKEN
+  if [[ -n "${PRESET:-}" ]]; then
+    export CLAUDE_CODE_OAUTH_TOKEN="$PRESET"
+  fi
+
+  STUB_MARKER="$marker" aidc::resolve_claude_oauth_token >"$out_file" 2>&1
+
+  RESULT_TOKEN="${CLAUDE_CODE_OAUTH_TOKEN:-}"
+  RESULT_OUTPUT="$(cat "$out_file")"
+  RESULT_CALLED=0
+  if [[ -f "$marker" ]]; then
+    RESULT_CALLED=1
+  fi
+  return 0
+}
+
+# 1. Token already in the environment: left untouched, Keychain never read.
+(
+  export PATH="$STUB_DIR:$PATH"
+  export STUB_TOKEN="$FAKE_TOKEN"
+  PRESET="preset-value"
+  run_resolver
+  if [[ "$RESULT_TOKEN" == "preset-value" && "$RESULT_CALLED" -eq 0 ]]; then
+    ok "preset env token is preserved"
+  else
+    fail "preset case: token='$RESULT_TOKEN' called=$RESULT_CALLED"
+  fi
+)
+
+# 2. Unset + stub returns a token: exported with that exact value, no leak.
+(
+  export PATH="$STUB_DIR:$PATH"
+  export STUB_TOKEN="$FAKE_TOKEN"
+  run_resolver
+  if [[ "$RESULT_TOKEN" == "$FAKE_TOKEN" && "$RESULT_CALLED" -eq 1 && "$RESULT_OUTPUT" != *"$FAKE_TOKEN"* ]]; then
+    ok "token resolved from Keychain without leaking to output"
+  else
+    fail "resolve case: token='$RESULT_TOKEN' called=$RESULT_CALLED output='$RESULT_OUTPUT'"
+  fi
+)
+
+# 3. Unset + stub returns empty: variable stays unset, no crash.
+(
+  export PATH="$STUB_DIR:$PATH"
+  export STUB_TOKEN=""
+  run_resolver
+  if [[ -z "$RESULT_TOKEN" ]]; then
+    ok "empty Keychain result leaves token unset"
+  else
+    fail "empty case: unexpected token '$RESULT_TOKEN'"
+  fi
+)
+
+# 4. Unset + stub exits non-zero: variable stays unset, no crash under set -e.
+(
+  export PATH="$STUB_DIR:$PATH"
+  export STUB_TOKEN="$FAKE_TOKEN"
+  export STUB_FAIL=1
+  run_resolver
+  if [[ -z "$RESULT_TOKEN" ]]; then
+    ok "failed Keychain lookup is handled gracefully"
+  else
+    fail "failed-lookup case: unexpected token '$RESULT_TOKEN'"
+  fi
+)
+
+# 5. Lookup disabled via empty service name: skipped, stub never called.
+(
+  export PATH="$STUB_DIR:$PATH"
+  export STUB_TOKEN="$FAKE_TOKEN"
+  export AIDC_CLAUDE_OAUTH_KEYCHAIN_SERVICE=""
+  run_resolver
+  if [[ -z "$RESULT_TOKEN" && "$RESULT_CALLED" -eq 0 ]]; then
+    ok "empty service name disables the lookup"
+  else
+    fail "disabled case: token='$RESULT_TOKEN' called=$RESULT_CALLED"
+  fi
+)
+
+# 6. Key removed from passthrough list (per-project opt-out): skipped.
+(
+  export PATH="$STUB_DIR:$PATH"
+  export STUB_TOKEN="$FAKE_TOKEN"
+  # Read indirectly by the sourced resolver, so shellcheck can't see the use.
+  # shellcheck disable=SC2034
+  AIDC_PASSTHROUGH_ENV_KEYS=("OPENAI_API_KEY")
+  run_resolver
+  if [[ -z "$RESULT_TOKEN" && "$RESULT_CALLED" -eq 0 ]]; then
+    ok "dropping key from passthrough disables resolution"
+  else
+    fail "opt-out case: token='$RESULT_TOKEN' called=$RESULT_CALLED"
+  fi
+)
+
+# 7. `security` not on PATH (e.g. non-macOS host): no-op, no error.
+(
+  empty_path="$TMP_ROOT/empty-path"
+  mkdir -p "$empty_path"
+  export PATH="$empty_path"
+  unset CLAUDE_CODE_OAUTH_TOKEN
+  aidc::resolve_claude_oauth_token >/dev/null 2>&1
+  if [[ -z "${CLAUDE_CODE_OAUTH_TOKEN:-}" ]]; then
+    ok "missing security tool is a clean no-op"
+  else
+    fail "missing-tool case: unexpected token '${CLAUDE_CODE_OAUTH_TOKEN:-}'"
+  fi
+)
+
+PASS_COUNT="$(wc -l <"$PASSED_FILE" | tr -d ' ')"
+FAIL_COUNT="$(wc -l <"$FAILED_FILE" | tr -d ' ')"
+printf '\n%s passed, %s failed\n' "$PASS_COUNT" "$FAIL_COUNT"
+[[ "$FAIL_COUNT" -eq 0 ]]