project-athena 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+## 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,7 +244,7 @@ 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`.
 
@@ -209,7 +299,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.