@alextis59/athena 1.0.0 → 1.2.0

package/docs/exec-plans/template.md

@@ -0,0 +1,67 @@
+# Execution Plan: <title>
+
+Date: <yyyy-mm-dd>
+
+## Goal
+
+Describe the user-visible outcome and the repository behavior that will change.
+
+## Scope
+
+In scope:
+
+- <files, modules, commands, docs, or workflows>
+
+Out of scope:
+
+- <explicitly deferred or preserved behavior>
+
+## Current Behavior
+
+Summarize what the code and docs do now. Link the relevant files, tests, and
+commands inspected before editing.
+
+## Constraints And Invariants
+
+- Preserve the `athena` binary name and `@alextis59/athena` package identity.
+- Preserve local-first defaults and explicit remote document-text opt-ins.
+- Preserve Athena-owned agent loop and citation validation unless this plan is
+  explicitly about changing them.
+- Preserve `pdf-2-llm` as the PDF ingestion path unless this plan is explicitly
+  about parser architecture.
+- Keep MCP read-only unless this plan includes a security design for writes.
+
+Add task-specific constraints here.
+
+## Plan
+
+1. Inspect the relevant code, docs, tests, and package scripts.
+2. Make the smallest implementation or documentation change that satisfies the
+   goal.
+3. Update adjacent docs, tests, fixtures, or debt notes when behavior changes.
+4. Run the validation below.
+5. Record results and any follow-up debt.
+
+## Validation
+
+Commands to run:
+
+```bash
+<command>
+```
+
+Expected outcomes:
+
+- <observable pass condition>
+
+If validation is skipped, record the reason and residual risk.
+
+## Rollback
+
+Describe how to revert the change or disable the behavior if validation fails
+after merge.
+
+## Notes
+
+Capture decisions, tradeoffs, and follow-up items that should survive the
+implementation turn.

package/docs/implementation-plan.md

@@ -1279,6 +1279,14 @@ Milestone 11 external agent documentation proof, 2026-07-03:
   returned 4 JSON-RPC responses, 6 tools, `docs/admin-guide.md` as the top
   search hit, and 1 read trace locator.
 
+Milestone 11 external agent provider option proof, 2026-07-05:
+
+- Added `agent.provider` with `opencode` as the default and `codex` as the
+  alternate provider.
+- Added `athena mcp --agent-provider <opencode|codex>` for one-off MCP setup.
+- Updated OpenCode and Codex MCP setup docs while preserving the same read-only
+  tool exposure for both providers.
+
 ## Release Readiness Checklist
 
 Use this before publishing a public package or tagging a release.

package/docs/index.md

@@ -0,0 +1,61 @@
+# Documentation Index
+
+Start with the root files, then use the task-specific docs below.
+
+## Agent Entry Points
+
+- [../AGENTS.md](../AGENTS.md): repository instructions for coding agents.
+- [../ARCHITECTURE.md](../ARCHITECTURE.md): current package, module, runtime,
+  data-flow, and invariant map.
+- [../README.md](../README.md): user-facing install, command, config, MCP, and
+  development quickstart.
+
+## Product And Implementation
+
+- [agentic-rag-specifications.md](agentic-rag-specifications.md): product and
+  engineering requirements for Athena's local-first documentation RAG behavior.
+- [agentic-rag-study.md](agentic-rag-study.md): source study behind the
+  architecture choices.
+- [implementation-plan.md](implementation-plan.md): milestone checklist and
+  historical proof notes for implementation work.
+- [mcp-integration.md](mcp-integration.md): OpenCode, Codex, and generic MCP
+  setup, exposed read-only tools, and manual stdio smoke test.
+- [validation-corpus.md](validation-corpus.md): corpus layout, licensing,
+  retrieval, cache, and coverage rules.
+
+## Harness Operations
+
+- [SECURITY.md](SECURITY.md): security model, local-first boundaries, secrets,
+  network, filesystem, MCP, and server exposure notes.
+- [QUALITY.md](QUALITY.md): validation ladder for docs, source changes,
+  retrieval/parser changes, corpus changes, package release checks, and manual
+  smoke tests.
+- [tech-debt-tracker.md](tech-debt-tracker.md): practical deferred work that is
+  visible from the current code and docs.
+- [exec-plans/template.md](exec-plans/template.md): reusable plan template for
+  larger changes.
+
+## Decisions
+
+- [adr/0001-sqlite-driver.md](adr/0001-sqlite-driver.md): why Athena uses
+  `better-sqlite3` for the local SQLite layer.
+
+## Source Map
+
+- `src/cli/`: command parsing and dispatch.
+- `src/config/`: default config, config loading, validation, and
+  `defineConfig()`.
+- `src/storage/`: `.athena/` paths, migrations, schema checks, and
+  transactions.
+- `src/indexer/`: discovery, hashing, parsing, chunking, embedding, and index
+  writes.
+- `src/parsers/`: text-like parsers, PDF parsing, chunking, and normalization.
+- `src/embeddings/`: local, Ollama, and remote embedding providers.
+- `src/retrieval/`: read-only retrieval tools and trace capture.
+- `src/agent/`: Athena-owned agent loop, model providers, tools, citations, and
+  turn persistence.
+- `src/server/`: local HTTP UI/API server.
+- `src/ui/`: static web UI.
+- `src/mcp/`: stdio MCP server.
+- `scripts/`: corpus and evaluation commands.
+- `test/`: Node test suites and validation corpus fixtures.

package/docs/mcp-integration.md

@@ -17,6 +17,31 @@ node dist/cli/main.js index --root /absolute/path/to/project
 For an installed package, replace `node dist/cli/main.js` with `athena` or
 `npx @alextis59/athena`.
 
+## Agent Provider Option
+
+OpenCode is the default external-agent provider. Use `--agent-provider codex`
+when the MCP server is configured for Codex:
+
+```sh
+athena mcp --root /absolute/path/to/project --agent-provider codex
+```
+
+The same choice can be made durable in `athena.config.ts`,
+`athena.config.mjs`, or `athena.config.json`:
+
+```ts
+import { defineConfig } from "@alextis59/athena";
+
+export default defineConfig({
+  agent: {
+    provider: "codex"
+  }
+});
+```
+
+The option changes client-specific initialization guidance only. The MCP server
+continues to expose the same read-only retrieval tools for every provider.
+
 ## OpenCode
 
 OpenCode configures MCP servers under the `mcp` key. A local MCP entry uses
@@ -66,6 +91,54 @@ Installed package example:
 After saving the config, run `opencode mcp list` to check that OpenCode can
 start the server and discover its tools.
 
+## Codex
+
+Codex stores MCP servers in `config.toml`. You can configure Athena in the
+user-level `~/.codex/config.toml` or in a trusted project-scoped
+`.codex/config.toml`.
+
+Installed package example:
+
+```toml
+[mcp_servers.athena]
+command = "npx"
+args = [
+  "--yes",
+  "@alextis59/athena",
+  "mcp",
+  "--root",
+  ".",
+  "--agent-provider",
+  "codex"
+]
+cwd = "/absolute/path/to/project"
+enabled = true
+startup_timeout_sec = 10
+tool_timeout_sec = 60
+```
+
+Development checkout example:
+
+```toml
+[mcp_servers.athena]
+command = "node"
+args = [
+  "/absolute/path/to/athena/dist/cli/main.js",
+  "mcp",
+  "--root",
+  ".",
+  "--agent-provider",
+  "codex"
+]
+cwd = "/absolute/path/to/project"
+enabled = true
+startup_timeout_sec = 10
+tool_timeout_sec = 60
+```
+
+After saving the config, start Codex in the project and use `/mcp` in the
+terminal UI to check that the `athena` server is connected.
+
 ## Exposed Tools
 
 Athena exposes only read-only retrieval tools:

package/docs/tech-debt-tracker.md

@@ -0,0 +1,21 @@
+# Tech Debt Tracker
+
+Track deferred work that is visible from the current implementation. Keep this
+file practical: each item should have a reason, a likely validation path, and a
+status.
+
+| Item | Context | Validation | Owner | Status |
+| --- | --- | --- | --- | --- |
+| Align chat provider docs and adapters | Config validation recognizes `openai`, `anthropic`, and `gemini` chat providers, but `createConfiguredModelProvider()` currently implements Ollama only after validation. Either add adapters or keep user docs explicit that non-Ollama chat adapters are not ready. | Provider tests plus `athena ask` smoke for each supported adapter. | TBD | Open |
+| Decide authenticated server posture before non-loopback use | The HTTP server is intentionally local and unauthenticated today. Binding `--host` to a non-loopback address should remain an operator-controlled advanced use until there is an authenticated mode. | Server tests for auth behavior if added; security doc update. | TBD | Open |
+| Evaluate query embedding parity for remote/provider-specific indexes | Indexed vectors can come from provider-specific embeddings. Retrieval currently builds query vectors inside the retrieval layer rather than routing the query through the configured embedding provider. Confirm whether this is acceptable for release quality or add provider-aware query embedding. | Retrieval/eval tests comparing hybrid, FTS-only, vector-only, and provider-backed query behavior. | TBD | Open |
+| Harden package smoke automation | Package readiness currently relies on manual tarball and `npx --package` smoke commands documented in `docs/QUALITY.md`. A script could reduce release mistakes while preserving the same checks. | New script plus tarball CLI smoke in a temp project. | TBD | Open |
+| Expand parser warning summaries | Doctor reports total parser warnings, while PDF warning detail is available in parser artifacts and retrieval responses. A future doctor view could summarize warning codes by source. | Doctor tests and fixture with repeated PDF warnings. | TBD | Open |
+
+## Closing Criteria
+
+Close an item only after:
+
+- the implementation or documentation change lands;
+- the validation in the row passes;
+- related docs are updated when behavior or policy changes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alextis59/athena",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Local-first agentic documentation RAG command.",
   "type": "module",
   "private": false,