project-athena 0.1.3 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,83 @@
+# Changelog
+
+## 0.2.1 — 2026-09-30
+
+Security release. Upgrading is recommended for everyone. After upgrading, run `athena sync` once (the `security.md` format changed) and, if you use the pre-commit hook with `--review`, run `athena git-hook install --review` again so it reviews staged changes.
+
+### Breaking
+
+- `athena review --base <ref>` exits with code 2 when the base can't be resolved or has no merge base with HEAD. Shallow CI clones need full history, e.g. `actions/checkout` with `fetch-depth: 0`.
+- `ai.baseUrl` and `ai.consent` in the committed `.athena/config.json` are now ignored (with a warning in `athena ai status`, `athena ai enrich` and `athena doctor`). Move them to the environment (`ATHENA_AI_BASE_URL`, `ATHENA_AI_CONSENT=1`), `.athena/local.json` (gitignored), or your user config (`~/.config/athena/config.json`, `$XDG_CONFIG_HOME/athena/config.json`, or `%APPDATA%\athena\config.json` on Windows). `provider`, `model`, `mode` and `maxChars` still work from `.athena/config.json`.
+- `--fail-on` now fails on unrated findings by default (`--unrated warn` to relax).
+- `security-scan.json` and `athena security --json`: severity `unknown` has been renamed to `unrated`, in both findings and `counts`. Old scan files are still read. Tools that run once per input have a new optional `target` field (for example `pip-audit` per requirements file).
+- The `security.md` format changed: the Fingerprint column was removed from Secret Management. Run `athena sync` to update it.
+
+### Security
+
+- `athena security --fail-on` now also fails when an audit tool ran but failed or timed out, since nothing was checked. A tool that isn't installed is still only reported. The web UI shows `unrated` findings.
+- **AI credential exfiltration**: a repository could set its own `ai.baseUrl` and `ai.consent` in `.athena/config.json` and receive your API key and knowledge. Both are now read only from machine-local sources (env > `.athena/local.json` > user config), providers refuse a base URL without a trusted source, and an Ollama endpoint that isn't loopback counts as remote and needs consent.
+- **Local server**: per-client rate limiting on `/api/*` (token bucket, 30 req/s, burst 120, 429 when exceeded); `--allow-remote` keeps the Host/Origin allowlist (bind address plus loopback) instead of disabling it, and warns that the connection is plain HTTP; `/api/context` clamps `maxChars` to 200,000; a failed security-scan start (e.g. missing `model.json`) no longer leaves every later scan stuck at 423; shutdown no longer hangs on open event streams.
+- **MCP**: every tool that returns repository content redacts secret-looking values and wraps the text in `<athena-document path="…" trust="untrusted-data">` delimiters with a note that it is project data, not instructions (embedded delimiters are neutralized).
+- **Agent hooks**: generated hook scripts quote `ATHENA_HOOK_COMMAND`, the agent name and the hook argument (POSIX single quotes; cmd.exe double quotes with `%` doubled), so paths with spaces, quotes, `$` or `&` can't break or inject into the script.
+- **Agent activity log**: commands and messages are additionally masked for `Authorization: Bearer|Basic …`, `--password …`, `mysql -p…` and `scheme://user:password@` credentials; rotation renames the log to `.agent-events.1.jsonl` (one generation kept) instead of rewriting it, so concurrent appends are never lost, and recent-event reads include the previous generation.
+- **GitHub Action**: the PR comment is only updated when it was written by `github-actions[bot]` and carries the versioned `<!-- athena-review:v1 -->` marker (the old marker is still recognized from the same bot), so another user's comment can't be hijacked. Review findings now also produce `::error`/`::warning` file annotations (with line numbers where available, escaped, never secret values).
+- **Web UI**: the Security and graph views refresh after `security.*` and `graph.*` events.
+- `athena review` scans each run of consecutive added lines as one block, so multi-line secrets such as PEM private keys are now flagged (at the line where they start, never with the value).
+- `athena review` fails closed on Git errors: a failing `git` command, an unknown `--base`, or a missing merge base (shallow clone) is now an error (exit 2) instead of an empty, "clean" review. Ctrl+C stops running `git` processes.
+- The diff is streamed with a 64 MB budget; a larger diff fails the review instead of being silently truncated.
+- `--base` now compares `merge-base(base, HEAD)..HEAD` for both the file list and the patch, so commits that exist only on the base branch no longer appear in the review.
+- The dependency check uses the analyzer's manifest parsers (`name =` / `version =` are no longer reported as dependencies), and a new manifest reports all of its dependencies.
+- New `athena review --staged` reviews the index (contents read from Git, untracked files ignored). The `--review` pre-commit hook now runs `athena review --staged --no-sync`, so unstaged or untracked files (such as a local `.env`) no longer block commits while staged secrets still do, and a review that can't run blocks the commit with its own message. Re-run `athena git-hook install --review` to update an installed hook.
+- Untracked files are read once, never through a symlink that points outside the project, and only up to 512 KB. Files that could not be checked are listed in a `skipped` warning (JSON: `incomplete`, `skipped`), and the review no longer says it found nothing to flag.
+- `athena security --fail-on` now counts findings the tool did not rate. pip-audit and govulncheck never report severity, so these findings were stored as `unknown` and never failed the build. They are now `unrated` and fail by default; `--unrated warn` reports them without failing.
+- pnpm audit output is parsed in pnpm's own advisories format. Before this, every pnpm project was reported as having no vulnerable dependencies.
+- An npm audit that reports an error (for example when offline) is now marked `failed` with npm's message. Before, it was reported as a clean audit. The same applies to empty or unrecognised output from any audit tool. npm exiting 1 because it found vulnerabilities still counts as a successful run.
+- govulncheck's multi-line JSON output is now parsed, and a vulnerability is reported only when govulncheck returns a finding for it. The title says whether the vulnerable code is called, only imported, or only required.
+- pip-audit now audits each `requirements*.txt` (`-r <file>`, at most 10), or a PEP 621 `pyproject.toml` as a project path. It no longer audits whichever Python environment is active. With nothing to audit, pip-audit is reported as `unavailable` with the reason "no requirements file to audit".
+- `athena security` scans the project files for secrets on every run. Before, it took the secret count from the cached `model.json`, so the count could be out of date.
+- Rewrote the secret patterns to remove catastrophic backtracking (ReDoS). `generic-secret-assignment` took over 1 s on 40 KB of crafted input. It now finds a bounded quoted value first, then checks the identifier before it (at most 64 chars) for a keyword. Private keys are matched by finding the BEGIN header and then the END within 16 KB. Open-ended token patterns now use bounded or lookbehind-anchored matches. Generic keyword patterns skip lines longer than 4096 characters. CI checks every pattern for time on crafted input and with the `recheck` ReDoS analyzer.
+- `security.md`, which is committed, no longer lists a fingerprint for each secret. The old value was an unsalted, truncated SHA-256 of the secret, so anyone could test guessed values against it offline. Secret fingerprints in `model.json` are now an HMAC keyed with the per-machine salt in `.athena/local.json` (gitignored), or with a random per-process key.
+
+## 0.2.0 — 2026-09-26
+
+- **Website link**: the terminal header, footer and next steps now link to https://athena.sabari.me, which is also the package homepage.
+- **Releases**: the release workflow uses npm trusted publishing (no stored token), adds provenance automatically, and creates a GitHub release from the changelog.
+- Source maps are no longer included in the npm package, and `CHANGELOG.md` is.
+- Fixed a CI race in the Ctrl+C test that failed on slower runners.
+- **Codex support**: `athena agents add codex` (also picked up by `athena init` when a `.codex/` folder exists). Athena writes its block in `AGENTS.md`, registers the MCP server in `.codex/config.toml` and installs activity hooks in `.codex/hooks.json`, keeping everything else in those files. `athena doctor` warns when Codex hasn't trusted the project yet, since Codex ignores `.codex/` until then. Athena only reads Codex's trust setting and never changes it.
+- **GitHub Copilot support**: `athena agents add copilot` (aliases `github-copilot`, `gh-copilot`). Athena writes a marked block in `.github/copilot-instructions.md`, registers the MCP server under `servers` in `.vscode/mcp.json`, and installs activity hooks in its own `.github/hooks/athena.json` (read by Copilot CLI and VS Code). Hook commands always exit 0, because Copilot denies a tool call when a pre-tool hook fails. `athena init` detects Copilot from `.github/copilot-instructions.md`, `.github/instructions/`, `.github/hooks/` or a `.vscode/mcp.json` Athena didn't create.
+- **Gemini CLI support**: `athena agents add gemini-cli`. Athena writes a marked block in `GEMINI.md`, and adds the `athena` MCP server and activity hooks (`SessionStart`, `BeforeAgent`, `BeforeTool`, `AfterAgent`, `SessionEnd`) to `.gemini/settings.json`, keeping everything else in those files.
+- `gemini` now selects Gemini CLI rather than Antigravity, and a `GEMINI.md` file no longer counts as evidence of Antigravity. `GEMINI.md` is Gemini CLI's context file; Antigravity also reads it, but so do other tools, so only `.agents/` or `.agent/` mean Antigravity is in use.
+- **Windsurf support**: `athena agents add windsurf` (alias `codeium`; picked up by `athena init` when `.windsurf/` or `.windsurfrules` exists). Athena writes an owned rule at `.windsurf/rules/athena.md` with `trigger: always_on`, kept under the documented 12,000-character limit; Windsurf and Devin Desktop (its new name) read it. MCP and activity hooks are not configured: Windsurf's MCP config is per user, and Cascade hooks only apply to the legacy Cascade agent (available through July 2026).
+- **Cline support**: `athena agents add cline` (picked up by `athena init` when `.clinerules` or `.cline/` exists). Athena writes an owned rule at `.clinerules/athena.md`; if `.clinerules` is a single file, Athena leaves it alone and uses `.cline/rules/athena.md`, which Cline also reads. MCP and activity hooks are not configured: Cline's MCP settings are per user, and its hooks are SDK plugins.
+- Removing one integration no longer removes the `AGENTS.md` block that another configured integration still uses.
+- **GitHub Action** (`uses: Sabari-Vasan-SM/athena@v0`): a composite action that runs `athena sync --check` and, on pull requests, `athena review --base <PR base>`, failing on stale knowledge or review blockers. With `comment: true` it keeps one pull request comment up to date with the findings (type and location only, never values). Outputs `in-sync` and `blockers`. Linux and macOS runners; see `examples/github-workflow.yml`.
+- **`athena git-hook install|uninstall|status`**: a `#!/bin/sh` pre-commit hook that blocks commits when `.athena/` is out of date (`--review` also blocks possible secrets and env files). It honours `core.hooksPath` and worktrees, adds a marked block to an existing shell hook instead of replacing it, refuses non-shell hooks and hooks managed by husky, lefthook or pre-commit (printing the `npx --no-install athena sync --check` line to use instead), and lets commits through when `athena` isn't installed.
+- `athena sync --check` no longer fails when only the Git change hotspots in `debugging.md` differ. They come from commit history and moved with every commit, so the check failed right after committing up-to-date knowledge. `--check --json` now includes `inSync` and `stale`.
+- Change hotspots no longer count commits to `.athena/` itself, and ties are ordered by path instead of commit recency.
+- `examples/demo-shop`: a small Express + Prisma project with its generated `.athena/` knowledge committed.
+
+## 0.1.3 — 2026-09-22
+
+- **Terminal UI**: `athena init`, `analyze` and `open` show a branded header (logo, links) sized to the terminal, a live checklist of the real pipeline stages with measured timings and results, and summary panels for project overview, generated files and next steps. It falls back to narrower layouts, plain text without Unicode, and no animation when output is not a TTY. `--json` and `--quiet` are unchanged.
+- `package.json` now links the GitHub repository, homepage and issue tracker.
+
+## 0.1.2 — 2026-09-18
+
+Republished with no functional changes.
+
+## 0.1.1 — 2026-09-18
+
+Packaging fix: the `bin` path in `package.json` is now `dist/cli.js`, and the description encoding was corrected. No functional changes.
+
+## 0.1.0 — 2026-09-18
+
+First public release.
+
+- **Analysis**: detects languages, frameworks, monorepos, commands, env var names, database schema, HTTP routes, auth signals, containers, CI and tests across 10 ecosystems. Every statement is labeled `FACT`, `DETECTED`, `INFERRED` or `UNKNOWN` with file/line evidence.
+- **Knowledge**: 11 generated Markdown documents in `.athena/`, plus the developer-owned `rules.md`. Generated sections are refreshed; your edits are preserved.
+- **Sync**: `athena sync` and `athena watch` propose updates only for documents that would actually change, with reasons and diffs. Nothing is written without review.
+- **Web UI**: `athena open` — knowledge viewer/editor, rules editor, sync review with diffs, security scan, context explorer and activity timeline, on `127.0.0.1` with a per-session token.
+- **Agents**: Claude Code, Cursor, Antigravity and AGENTS.md integrations, including activity hooks and MCP registration.
+- **Security & review**: `athena security` runs the audit tools your ecosystems provide; `athena review` checks the current diff for secrets, missing tests, new dependencies and more.
+- **Intelligence**: project graph, deterministic context engine (`athena context`), MCP server (`athena mcp`), and optional consent-gated AI suggestions (`athena ai`).

package/README.md

@@ -2,7 +2,9 @@
 
 **Project intelligence for AI coding agents.**
 
-Athena analyzes your repository and maintains a structured, human-readable understanding of it in `.athena/`: architecture, database, API, auth, security, testing, deployment, and your own project rules. It then points Claude Code, Cursor, Antigravity and other agents at that knowledge, so they plan and change code with real project context.
+🌐 **Website & docs:** [athena.sabari.me](https://athena.sabari.me) · 📦 [npm](https://www.npmjs.com/package/project-athena) · [Changelog](CHANGELOG.md)
+
+Athena analyzes your repository and maintains a structured, human-readable understanding of it in `.athena/`: architecture, database, API, auth, security, testing, deployment, and your own project rules. It then points Claude Code, Cursor, Codex, GitHub Copilot, Gemini CLI, Antigravity, Windsurf, Cline and other agents at that knowledge, so they plan and change code with real project context.
 
 Athena doesn't replace your coding agent, and it doesn't claim to make code bug-free or secure. It makes agents more **project-aware**, and it is honest about what it knows.
 
@@ -57,10 +59,11 @@ Generated content sits between `athena:generated` markers. Anything outside the
 | `athena watch` | Watch the project and propose updates as files change (`--auto-apply` to write automatically) |
 | `athena doctor` | Check the installation, project, knowledge files and agent integrations |
 | `athena rules` | `list`, `add "<rule>" --section <name>`, `edit`, `enable`, `disable`, `remove` |
-| `athena agents` | `list`, `add <claude-code\|cursor\|antigravity\|agents-md\|all>`, `remove` |
+| `athena agents` | `list`, `add <claude-code\|cursor\|codex\|copilot\|gemini-cli\|antigravity\|windsurf\|cline\|agents-md\|all>`, `remove` |
 | `athena activity` | Show AI agent activity observed through hooks (`-n`, `--agent`) |
 | `athena security` | Audit dependencies with the tools installed for this project, and report secret findings (`--fail-on`, `--last`, `--no-audit`) |
 | `athena review` | Check the current diff for facts worth reviewing, and list your rules and checklist (`--base`, `--no-fail`) |
+| `athena git-hook` | `install` (`--review`), `uninstall`, `status` — a Git pre-commit hook that blocks commits when knowledge is out of date |
 | `athena context <task>` | Show which knowledge an agent should read for a task (`--full`, `--json`) |
 | `athena graph` | Inspect the project graph (`--build`, `--search`, `--node`, `--kind`) |
 | `athena mcp` | Serve project intelligence to agents over MCP (stdio; `--allow-write`) |
@@ -100,7 +103,7 @@ Apply updates to 2 documents? [y/N]
 - **Nothing is written without review.** `athena watch` and the web UI only propose updates. You can apply or ignore a proposal (an ignored proposal stays quiet until the files change again), or opt in to `--auto-apply`.
 - **Your edits are still safe.** Developer-edited sections are preserved and listed. Applying is refused if a document changed after the proposal was made.
 - When files change but no knowledge is affected, only the local index is refreshed.
-- `athena sync --check` exits with 1 when knowledge is out of date, which is useful in CI or a pre-commit hook.
+- `athena sync --check` exits with 1 when knowledge is out of date, which is useful in CI or a pre-commit hook (see [Use in CI and git hooks](#use-in-ci-and-git-hooks)). Change hotspots come from Git history and move with every commit, so the check ignores them; `athena sync` still refreshes them.
 - Ignore rules: defaults, root and nested `.gitignore` files, `.git/info/exclude`, and `.athena/config.json`.
 
 ## Watching what agents do
@@ -111,7 +114,12 @@ Athena configures hooks for agents that support them, so it can show what they a
 |---|---|
 | Claude Code | Hooks in `.claude/settings.json` running `athena event` (async, so the agent is never blocked) |
 | Cursor | Hooks in `.cursor/hooks.json` plus a small forwarding script |
+| Codex | Hooks in `.codex/hooks.json` running `athena event` (Codex loads them only for trusted projects) |
+| GitHub Copilot | Hooks in `.github/hooks/athena.json` running `athena event` (read by Copilot CLI and VS Code, where hooks are in Preview). Each command always exits 0, so a machine without Athena — such as Copilot cloud agent — is never blocked |
+| Gemini CLI | Hooks in `.gemini/settings.json` running `athena event` (Gemini CLI warns once when it sees new project hooks) |
 | Antigravity | No documented hook mechanism — activity is reported as unavailable |
+| Windsurf | Not installed: Cascade hooks applied only to the legacy Cascade agent, which Devin Desktop (Windsurf's new name) kept available only through July 2026 — activity is reported as unavailable |
+| Cline | Not installed: Cline's hooks are SDK plugins (TypeScript) that don't run in the IDE extensions — activity is reported as unavailable |
 
 Hooks append events to `.athena/.agent-events.jsonl` (gitignored, rotated, no network). The UI tails that file, so activity shows up live and history survives with the UI closed.
 
@@ -136,6 +144,88 @@ athena review                     # check the current diff before you commit
 
 **`athena review`** checks facts about your current diff: secrets in added lines (a blocker, exit 1), committed env files, new dependencies, source changed without tests, API/schema/auth touchpoints, large files, debug leftovers, and whether Athena knowledge is stale. It then lists your enabled rules and the project's review checklist for you or your agent to apply — Athena does not claim to judge whether they are met, and it runs no AI.
 
+## Use in CI and git hooks
+
+Commit `.athena/` so your team and CI share it. Athena can then keep it honest in two places.
+
+### GitHub Action
+
+```yaml
+# .github/workflows/athena.yml
+on: pull_request
+permissions:
+  contents: read
+  pull-requests: write # only for `comment: true`
+jobs:
+  athena:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # the review diffs the pull request against its base commit
+      - uses: Sabari-Vasan-SM/athena@v0
+        with:
+          comment: true
+```
+
+| Input | Default | |
+|---|---|---|
+| `check-sync` | `true` | Run `athena sync --check`; fail when `.athena/` is out of date |
+| `review` | `true` | On `pull_request` events, run `athena review --base <PR base>`; fail on blockers (possible secrets, committed env files). Skipped on other events |
+| `review-base` | PR base SHA | Ref to review against, for example on `push` events |
+| `comment` | `false` | Post the findings as one pull request comment and update it on later pushes (marked with `<!-- athena-review -->`) |
+| `version` | `latest` | `project-athena` version to install with `npm install -g` |
+| `working-directory` | `.` | Folder that contains `.athena/` |
+| `github-token` | `github.token` | Token for the comment |
+
+Outputs: `in-sync` (`true`/`false`) and `blockers` (a count). The comment and logs show each finding's type and file location, never the matched value.
+
+- The action uses Node.js if it is already 22.12 or newer, and otherwise installs Node.js 22 with `actions/setup-node`.
+- It is a composite action written in bash, so it runs on Linux and macOS runners. Windows runners are not supported.
+- Without `fetch-depth: 0` the base commit is missing and the review step fails with a message saying so.
+- Pull requests from forks get a read-only token, so the comment is skipped with a warning; the checks still run.
+
+A complete workflow is in [examples/github-workflow.yml](examples/github-workflow.yml).
+
+### Git pre-commit hook
+
+```text
+$ athena git-hook install
+✓ Installed the pre-commit hook (knowledge check) at .git/hooks/pre-commit
+Commits are blocked when .athena/ knowledge is out of date. Teammates without Athena installed are not blocked.
+Using husky, lefthook or pre-commit? Add `npx --no-install athena sync --check` to its pre-commit config instead.
+
+$ git commit -m "Add refunds"
+Proposed: api.md, security.md
+Knowledge is out of date. Run `athena sync` to review and apply.
+athena: commit blocked: .athena/ knowledge is out of date. Run `athena sync`, stage .athena/ and commit again (or skip once with `git commit --no-verify`).
+```
+
+- `athena git-hook install --review` also runs `athena review` and blocks commits that add possible secrets or env files. It checks the whole working tree (staged, unstaged and untracked files that aren't ignored), not only what is staged.
+- The hook is a `#!/bin/sh` script in the directory Git actually uses (`git rev-parse --git-path hooks`), so `core.hooksPath` and linked worktrees work. For a project in a subfolder of the repository, the hook runs Athena there.
+- If `athena` is not on `PATH`, the hook prints a note and lets the commit through, so it never blocks teammates who don't use Athena.
+- **An existing pre-commit hook is kept.** If it is a shell script, Athena adds its block between `# athena:start` and `# athena:end` right after the shebang, so it runs before your own commands. Athena refuses to touch hooks written in other languages and hooks it recognizes as managed by husky, lefthook or pre-commit (from `core.hooksPath` or the hook's contents), and prints the line to add instead.
+- `athena git-hook uninstall` removes only Athena's block (or the file, if Athena created it). `athena git-hook status` shows what is installed.
+
+**husky, lefthook and other hook managers:** add one line to your pre-commit config instead of installing the hook. It needs `project-athena` as a devDependency or installed globally.
+
+```bash
+# .husky/pre-commit
+npx --no-install athena sync --check
+```
+
+```yaml
+# lefthook.yml
+pre-commit:
+  commands:
+    athena:
+      run: npx --no-install athena sync --check
+```
+
+### Example project
+
+[examples/demo-shop](examples/demo-shop) is a small Express + Prisma API with its generated `.athena/` knowledge committed, so you can see what Athena writes before running it on your own code. See [examples/README.md](examples/README.md).
+
 ## Context engine, graph and MCP
 
 Reading twelve documents for every task wastes an agent's context. Athena picks what matters:
@@ -154,9 +244,9 @@ Documents to read
 - **Sections, not whole files.** Only the relevant sections are returned, under a character budget, with your rules always included.
 - **Project graph.** `athena graph --build` writes `.athena/graph.json`: packages, files, routes, entities, frameworks and commands, connected by `contains`, `imports`, `handles`, `defines` and `depends_on`. It comes from the analysis, so it never asserts more than DETECTED evidence.
 
-**MCP.** `athena mcp` serves this to any MCP-capable agent over stdio, and `athena agents add` registers it (`.mcp.json` for Claude Code, `.cursor/mcp.json` for Cursor). Tools: `get_relevant_context`, `get_project_context`, `get_architecture`, `get_database_schema`, `get_api_context`, `get_security_context`, `get_project_rules`, `get_knowledge_document`, `get_project_changes`, `get_project_graph`, `get_athena_status`, `update_knowledge`.
+**MCP.** `athena mcp` serves this to any MCP-capable agent over stdio, and `athena agents add` registers it (`.mcp.json` for Claude Code, `.cursor/mcp.json` for Cursor, `[mcp_servers.athena]` in `.codex/config.toml` for Codex, `servers.athena` in `.vscode/mcp.json` for GitHub Copilot in VS Code, `mcpServers.athena` in `.gemini/settings.json` for Gemini CLI). Tools: `get_relevant_context`, `get_project_context`, `get_architecture`, `get_database_schema`, `get_api_context`, `get_security_context`, `get_project_rules`, `get_knowledge_document`, `get_project_changes`, `get_project_graph`, `get_athena_status`, `update_knowledge`.
 
-The server is **read-only by default**: `update_knowledge` reports what would change and refuses to write unless you start it with `--allow-write`.
+The server is **read-only by default**: `update_knowledge` reports what would change and refuses to write unless you start it with `--allow-write`. Repository content it returns is passed through the secret redactor and wrapped in `<athena-document … trust="untrusted-data">` delimiters, so agents can tell project data from instructions.
 
 ## Optional AI
 
@@ -168,8 +258,9 @@ athena ai enrich --dry-run        # show exactly what would be sent
 athena ai enrich --consent        # ask for suggestions
 ```
 
-- **Providers:** Anthropic, OpenAI, Google, and Ollama for a fully local setup. Configure in `.athena/config.json` under `"ai"`; API keys come from environment variables only and are never written to disk by Athena.
-- **Consent first.** Nothing leaves your machine without `--consent` (or `"consent": true`). `--dry-run` prints the provider, endpoint, documents and exact size first.
+- **Providers:** Anthropic, OpenAI, Google, and Ollama for a fully local setup. Choose `provider`, `model` and `maxChars` in `.athena/config.json` under `"ai"`; API keys come from environment variables only and are never written to disk by Athena.
+- **Trusted settings stay on your machine.** `.athena/config.json` is committed, so anyone who can push to the repository controls it. The two settings that decide where your API key and knowledge go — `baseUrl` (a custom endpoint or remote Ollama) and `consent` — are therefore only read from machine-local sources, in this order: environment variables `ATHENA_AI_BASE_URL` and `ATHENA_AI_CONSENT=1`; `.athena/local.json` (gitignored), e.g. `{ "ai": { "baseUrl": "https://proxy.internal", "consent": true } }`; your user config at `~/.config/athena/config.json` (`$XDG_CONFIG_HOME/athena/config.json`, or `%APPDATA%\athena\config.json` on Windows) with the same `"ai"` shape. If `.athena/config.json` sets them, Athena ignores them and says so in `athena ai status`, `athena ai enrich` and `athena doctor`.
+- **Consent first.** Nothing leaves your machine without consent: `athena ai enrich --consent`, `ATHENA_AI_CONSENT=1`, or `"consent": true` in `.athena/local.json` or your user config. An Ollama endpoint that isn't `localhost`/`127.0.0.1`/`::1` counts as remote and needs consent too. `--dry-run` prints the provider, endpoint, documents and exact size first.
 - **Knowledge only, redacted.** Athena sends your `.athena` documents — never source code — after the secret redactor, and refuses to send anything that still looks like a secret.
 - **Output is INFERRED.** Suggestions land in `.athena/ai-suggestions.md` (gitignored), clearly labeled and attributed to the model. Nothing is added to your knowledge base automatically.
 
@@ -209,7 +300,12 @@ Security: the server binds to `127.0.0.1` only, on the first free port from 7432
 |---|---|
 | Claude Code | A marked block in `CLAUDE.md` that imports `.athena/rules.md` |
 | Cursor | `.cursor/rules/athena.mdc` (always applied) |
+| Codex | The marked block in `AGENTS.md` (which Codex reads), plus `.codex/config.toml` and `.codex/hooks.json`. Codex ignores `.codex/` until you trust the project; `athena doctor` tells you if it isn't trusted yet |
+| GitHub Copilot | A marked block in `.github/copilot-instructions.md`, the `athena` server in `.vscode/mcp.json`, and `.github/hooks/athena.json` |
+| Gemini CLI | A marked block in `GEMINI.md`, plus the `athena` MCP server and hooks in `.gemini/settings.json`. If you enabled Gemini CLI's folder trust, trust the project, or it ignores `.gemini/settings.json` |
 | Antigravity | `.agents/rules/athena.md` (set to *Always On* in Antigravity if needed) |
+| Windsurf | `.windsurf/rules/athena.md` (`trigger: always_on`, under the 12,000-character limit), read by Windsurf and Devin Desktop. MCP is per-user in Windsurf, so add `athena mcp` to your `mcp_config.json` yourself |
+| Cline | `.clinerules/athena.md`, or `.cline/rules/athena.md` if `.clinerules` is a single file (Athena never touches that file). MCP is per-user in Cline, so add `athena mcp` in Cline's MCP settings yourself |
 | Others | A marked block in `AGENTS.md` |
 
 The instructions include a **relevance map**. A database task reads `database.md`, `architecture.md`, `api.md`, `security.md`, `testing.md` and `rules.md`, while a styling tweak reads only `project.md`, `architecture.md` and `rules.md`. Agents don't load everything for every task.