@inventeer.tech/apex 0.2.32 → 0.2.33

package/README.md

@@ -2,7 +2,7 @@
 
 **AI-powered software delivery agent. From task description to open pull request — across multiple repos.**
 
-[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey?style=flat)]()
+[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey?style=flat)]()
 [![License MIT](https://img.shields.io/badge/license-MIT-blue?style=flat)](https://github.com/Inventeer/apex/blob/main/LICENSE)
 [![npm](https://img.shields.io/npm/v/@inventeer.tech/apex?style=flat)](https://www.npmjs.com/package/@inventeer.tech/apex)
 
@@ -10,47 +10,120 @@
 
 ## What is APEX?
 
-APEX is a terminal CLI that turns a ticket (`ENG-123`) into merged pull requests across all your repositories — autonomously. You describe the task, approve the plan, and watch the code land in real time.
+APEX is a terminal CLI that takes a developer from a Linear ticket to open pull requests across all their repositories — with full codebase awareness, persistent memory, and zero configuration files left in repos.
 
-```
-You type:   /eng.start ENG-123
-APEX does:  fetches the ticket → reads all your repos → proposes a cross-repo plan
-You press:  [A] to approve
-APEX does:  writes the code, runs tests, opens one PR per repo
-```
+You describe the task, approve the plan, and watch the changes land in real time across every repository in your stack.
 
 **What runs on your machine:** the `apex` binary, a native AI runtime engine, and your git repos.  
 **What lives in the cloud:** codebase semantic search (RAG), episodic session memory, LLM proxy, org config.  
-**What never happens:** files created in your repos, credentials stored anywhere besides `~/.apex/`.
+**What never happens:** files created in your repos.
 
 ---
 
 ## Install
 
 ```bash
+# npm (cross-platform)
 npm install -g @inventeer.tech/apex
-```
-
-The binary is self-contained — no Go, Docker, or external runtime required.
-
-**Other install methods:**
 
-```bash
 # macOS — Homebrew
 brew install Inventeer/tap/apex
-
-# macOS / Linux — shell script
-curl -fsSL https://install.apex.dev | sh
 ```
 
-Verify:
+The binary is self-contained — no Go, Docker, or external runtime required.
 
 ```bash
-apex version
+apex version   # verify install
+apex doctor    # run pre-flight checks
 ```
 
 ---
 
+## Why APEX is Different
+
+| | Terminal AI assistant | Autonomous cloud agent | **APEX** |
+|---|---|---|---|
+| **Scope** | One file at a time | One task, one repo | One task, **all repos** |
+| **Execution** | Local, inline edits | Remote sandbox — you wait | Local — you watch changes live |
+| **Plan approval** | No | No | **Yes — nothing runs without your sign-off** |
+| **Memory between sessions** | None | Limited | **Episodic memory — resumes in <500 tokens** |
+| **Codebase context** | Open files only | Repo snapshot | **Full RAG across all repos, always fresh** |
+| **Org knowledge** | None | None | **ADRs, runbooks, specs — permanently searchable** |
+| **Architectural decisions** | None | None | **Logged automatically, queryable** |
+| **Delivery workflow** | Chat | Autonomous | **Phased: investigate → plan → implement → validate → ship** |
+| **Quality gate** | Manual | Basic CI | **Pre-PR: tests + lint + type check + auto-fix** |
+| **Token visibility** | None | None | **Per-model usage tracking** |
+
+### An invisible senior engineer on every task
+
+Every time you run a command in APEX, a curated framework of specialized agents, skills, and guardrails activates silently in the background — loaded from the cloud at startup, invisible to you, updating without any action on your part.
+
+**8 specialized agents** swap in automatically depending on what you're doing:
+
+- `/eng.start` activates the delivery agent — investigates, recalls past sessions, maps cross-repo dependencies
+- `/eng.pre-pr` activates the code reviewer + QA test planner in parallel
+- `/eng.debug` activates the bug hunter — root-cause analysis, not guessing
+- `/qa-gate` activates the quality champion with numeric scoring
+
+**30+ operational skills** activate on demand, invisibly:
+
+- Detected sequential DB writes? The `eng-database` skill activates — transaction boundaries, rollback scenarios, isolation levels
+- Found `.graphql` files in scope? The `eng-graphql` skill activates — schema validation, codegen, type contracts
+- Pre-PR check? `qa-static-analysis`, `qa-security-scan`, `qa-test-plan`, and `eng-confidence` run in sequence
+- Opening PRs? `eng-pr` and `eng-github` ensure branch naming, commit conventions, and cross-repo dependency notes
+
+**Phase guardrails enforced by rules, not discipline:**
+
+- `/eng.start` — no code written, analysis only
+- `/eng.plan` — no code, no commits, plan only
+- `/eng.work` — no commits until `/eng.pr`
+- Acceptance criteria must exist before investigation proceeds
+- Breaking changes require documented consumer impact
+
+None of this requires configuration. It's part of every session, for every developer in your organization.
+
+---
+
+### Multi-repo by design
+
+A workspace groups all your repositories. One task can plan, write, test, and open PRs across your backend, frontend, and shared types simultaneously. The AI knows your full stack — not just the file you have open.
+
+### Five layers of always-active context
+
+Every LLM call carries five layers injected automatically — you never paste context manually:
+
+- **Codebase RAG** — every file across all repos, chunked and semantically indexed. The AI knows your schema when writing the endpoint, and your types when writing the frontend.
+- **Episodic memory** — when you close the terminal, APEX saves a structured summary (completed, pending, files changed, decisions made, next steps). The next session resumes in under 500 tokens. After months of work, APEX still knows why things were built the way they were.
+- **Org knowledge base** — ADRs, runbooks, API specs, onboarding docs uploaded with `apex knowledge add` are permanently searchable. The AI cites your actual documentation instead of inventing conventions.
+- **Working context** — the full active session state, preserved mid-task.
+- **Framework intelligence** — curated engineering agents, quality guardrails, and delivery workflows loaded at startup. No configuration required.
+
+### Plan before code — you stay in control
+
+APEX never writes a line of code without showing you a phased plan first. You approve, edit, or cancel before any file is touched. Every run of `/eng.work` is a deliberate, reviewed commitment.
+
+### Built-in quality gates
+
+`/eng.pre-pr` runs tests, type checks, and lint across all repos before any PR is opened. Failures are auto-fixed up to 3 times. You see a scored quality report before anything goes to review.
+
+### Self-correcting execution loop
+
+The AI doesn't stop on the first test failure. It diagnoses the error, tries a different strategy, and escalates through recovery hints before surfacing a report. Sessions run until real progress stops — not until a fixed step count is hit.
+
+### Architectural decisions, not just code
+
+Every decision the AI makes — why it chose an approach, what it considered — is recorded automatically and stored. Run `apex decisions` to see the full log. New team members can understand why the code was written the way it was.
+
+### Always-fresh codebase context
+
+Push webhooks trigger incremental re-indexing automatically on every commit. The TUI shows an amber warning when the index is stale. The AI is never working from outdated code.
+
+### Token visibility, per model
+
+Every LLM call is metered. Run `apex usage` to see token consumption broken down by model and provider. No surprise bills, no silent runaway sessions.
+
+---
+
 ## The Workspace Concept
 
 > This is the most important thing to understand about APEX.
@@ -64,11 +137,11 @@ workspace: payment-platform
   └── shared-types/     (TypeScript contracts)
 ```
 
-When APEX works on `ENG-123: add refund endpoint`, it will:
-- Read the backend schema, frontend payment hooks, and shared type definitions
-- Generate a plan that touches all three repos
-- Write changes across all repos at once
-- Open one PR per repo, with cross-repo dependency notes
+When APEX works on `ENG-123: add refund endpoint`, it:
+- Reads the backend schema, frontend payment hooks, and shared type definitions
+- Generates a plan that touches all three repos
+- Writes changes across all repos in one session
+- Opens one PR per repo, with cross-repo dependency notes in each body
 
 **You register each repo once**, then forget about it:
 
@@ -82,61 +155,26 @@ APEX detects the git remote and technology stack automatically. All three repos
 
 ---
 
-## Full Setup Walk-through
-
-Follow these steps once to go from zero to your first AI-assisted PR.
+## Setup (once per machine)
 
-### Step 1 — Authenticate with GitHub
+### 1 — Install and authenticate
 
 ```bash
+npm install -g @inventeer.tech/apex
 apex login
 ```
 
-Opens the GitHub Device Flow in your browser. After approval, APEX stores a JWT in `~/.apex/credentials`. No API keys needed for this step.
+`apex login` opens the GitHub Device Flow in your browser. After approval, your organization's AI configuration — models, credentials, and behavior — is loaded automatically from the cloud.
 
-### Step 2 — Configure a model provider
-
-APEX needs an LLM API key. Add at least one:
+### 2 — Connect Linear
 
 ```bash
-# Anthropic Claude (recommended)
-apex config set anthropic_api_key  sk-ant-...
-apex config set default_model      anthropic/claude-opus-4-5
-
-# Or OpenAI
-apex config set openai_api_key     sk-...
-apex config set default_model      openai/gpt-4o
-
-# Or Google Gemini
-apex config set google_api_key     AI...
-apex config set default_model      google/gemini-2.0-flash
-```
-
-You can configure separate models for planning (reasoning) vs. coding (speed):
-
-```bash
-apex config set planning_model  anthropic/claude-opus-4-5
-apex config set coding_model    anthropic/claude-sonnet-4-5
-```
-
-### Step 3 — Connect your issue tracker (optional but recommended)
-
-```bash
-# Linear
 apex auth linear
-
-# Jira
-apex config set jira_base_url   https://myorg.atlassian.net
-apex config set jira_api_token  ...
-apex config set jira_email      you@company.com
-
-# GitHub (for PRs)
-apex config set github_token  ghp_...
 ```
 
-When Linear or Jira is connected, APEX fetches the full ticket description, acceptance criteria, and linked issues before starting any work.
+This opens the Linear OAuth flow. Once connected, APEX fetches full ticket details, acceptance criteria, and linked issues every time you start a task with a Linear ID.
 
-### Step 4 — Register your repos
+### 3 — Register your repos
 
 Run from inside each repository you want APEX to work with:
 
@@ -145,46 +183,29 @@ cd ~/repos/backend      && apex init
 cd ~/repos/frontend     && apex init
 ```
 
-Both repos are added to the same workspace automatically (based on git remote).
+APEX auto-detects the git remote and groups repos into a workspace.
 
-### Step 5 — Index the codebase
+### 4 — Index the codebase
 
 ```bash
 apex index
 ```
 
-This reads all source files, chunks them into 100-line overlapping segments, generates semantic embeddings, and stores them for search. Run this once after registration, and again after large changes.
+Reads all source files, chunks them into overlapping segments, generates semantic embeddings, and stores them for search. Run once after registration, and again after large changes.
 
-> The TUI shows an amber warning when the index is more than 24 hours old.
+> The TUI shows an amber warning when the RAG index is more than 24 hours old.
 
-### Step 6 — Verify everything is working
-
-```bash
-apex doctor
-```
-
-Expected output:
-
-```
-✅ native runtime: built-in
-✅ model API key: anthropic configured
-✅ workspace: backend, frontend registered
-✅ gateway: connected
-```
-
-Fix any ❌ items before continuing.
-
-### Step 7 — Launch
+### 5 — Launch
 
 ```bash
 apex
 ```
 
-APEX opens the workspace selector and the 3-panel TUI:
+APEX opens the workspace selector and the 3-panel TUI. From here, everything happens through slash commands.
 
 ```
 ╔═══════════════════════════════════════════════════════════════════════════╗
-║  APEX  ▸  payment-platform                                   v0.2.30     ║
+║  APEX  ▸  payment-platform                                   v0.2.32     ║
 ╠══════════════════╦════════════════════════════════╦════════════════════════╣
 ║  Workspace       ║                                ║  Live Diff             ║
 ║  ──────────────  ║   APEX                         ║  ────────────────────  ║
@@ -193,8 +214,8 @@ APEX opens the workspace selector and the 3-panel TUI:
 ║  • shared-types  ║   › 4,139 files in RAG         ║    client.ts  +12 -3   ║
 ║                  ║   › Episodic memory: 7 sessions║                        ║
 ║  Sessions        ║                                ║  frontend/             ║
-║  ─────────────── ║   Type /eng.start ENG-XX       ║   src/checkout/        ║
-║  1 paused        ║   or describe your task        ║    Payment.tsx  +8 -1  ║
+║  ─────────────── ║   Type /init-apex to begin     ║   src/checkout/        ║
+║  1 paused        ║   or /warm-up to load context  ║    Payment.tsx  +8 -1  ║
 ╠══════════════════╩════════════════════════════════╩════════════════════════╣
 ║  ›  _                                                                     ║
 ╚═══════════════════════════════════════════════════════════════════════════╝
@@ -204,133 +225,123 @@ APEX opens the workspace selector and the 3-panel TUI:
 
 ## The Delivery Workflow
 
-Once APEX is running, this is the typical sequence for any engineering task:
+Every engineering task follows this sequence inside the TUI.
+
+---
 
-### `/init-apex`  ·  Initialize the workspace
+### `/init-apex`  ·  Initialize (first use)
 
 ```
 /init-apex
 ```
 
-Runs on first use or after significant codebase changes. APEX loads your workspace configuration, reads your `ENV.md` files, and prepares the context.
+Run once when starting in a new workspace. APEX loads your organization's configuration, reads environment files across repos, and bootstraps the session context.
 
 ---
 
-### `/warm-up`  ·  Load context before starting
+### `/warm-up`  ·  Load context (start of each day)
 
 ```
 /warm-up
 ```
 
-APEX reads git status across all repos, loads recent decisions, and summarizes the current workspace state. Run this at the start of each day or session. Takes ~30 seconds.
+APEX reads git status across all repos, loads recent architectural decisions, recalls past sessions, and builds a fresh summary of where things stand. Run this each morning or at the start of a new session. Takes ~30 seconds.
 
 ---
 
-### `/eng.start ENG-XX`  ·  Investigate and plan
+### `/eng.start ENG-XX`  ·  Investigate
 
 ```
 /eng.start ENG-123
 ```
 
-APEX:
-1. Fetches the Linear/Jira ticket (description, ACs, linked issues)
-2. Recalls relevant past sessions from episodic memory
-3. Searches the codebase for related code via semantic RAG
-4. Analyzes all affected repos
-5. Produces a phased cross-repo implementation plan
+APEX fetches the Linear ticket (description, acceptance criteria, linked issues), recalls relevant past sessions from episodic memory, and searches the codebase via semantic RAG. It produces a full cross-repo investigation report with a clear problem statement and scope.
 
-You review the plan and press:
+---
+
+### `/eng.plan`  ·  Build the execution plan
+
+```
+/eng.plan
+```
+
+Based on the investigation, APEX generates a phased cross-repo implementation plan — broken into atomic tasks, one per file or concern, across all affected repos. Review the plan carefully.
 
 ```
   [ A ] Approve   [ E ] Edit   [ C ] Cancel
 ```
 
+Nothing is written until you approve.
+
 ---
 
-### `/eng.work`  ·  Execute the plan
+### `/eng.work`  ·  Execute
 
 ```
 /eng.work
 ```
 
-APEX writes code across all workspace repos following the approved plan. The **Live Diff panel** on the right updates in real time as files change. The AI runs tests as it goes and self-corrects up to 3 times on failures.
+APEX executes the approved plan. The **Live Diff panel** updates in real time as files change across every repo. The AI runs tests as it goes, self-corrects on failures (up to 3 attempts per task), and records every architectural decision it makes.
 
-You can watch, or come back when it's done.
+You can watch, step away, or answer questions if prompted.
 
 ---
 
-### `/eng.pre-pr`  ·  Validate before opening PRs
+### `/eng.pre-pr`  ·  Quality gate
 
 ```
 /eng.pre-pr
 ```
 
-APEX runs a full quality gate across all repos:
+Before opening PRs, APEX runs a full validation pass across all repos:
 - Unit and integration tests
 - Type checking
 - Lint
-- Cross-repo dependency validation
+- Cross-repo dependency consistency
 
-Any failures are auto-fixed. You get a quality report with a pass/fail score.
+Failures are auto-fixed. You receive a scored quality report with a pass/fail verdict.
 
 ---
 
-### `/eng.pr`  ·  Open pull requests
+### `/eng.pr`  ·  Ship
 
 ```
 /eng.pr
 ```
 
-APEX opens **one PR per repo**, each containing:
+APEX opens **one PR per repo**, each with:
 - A description derived from the ticket
-- A list of files changed and why
-- Cross-repo dependency notes (e.g. "this PR requires `shared-types#42` to be merged first")
-- Linear/Jira ticket status updated automatically
+- A summary of what changed and why
+- Cross-repo dependency notes (e.g. `shared-types#42` must merge first)
+- Linear ticket status updated automatically
 
 ---
 
-## Session Memory
-
-APEX remembers everything between sessions.
-
-When you close the terminal or pause a session, APEX generates a structured summary:
-- What was completed
-- What is pending
-- Which files were modified
-- Architectural decisions made
-- Next steps
-
-The next time you start a session on a similar task, that context is automatically injected into the AI — in under 500 tokens of overhead.
-
-```bash
-# List paused sessions
-apex session list
+## Session Memory in Practice
 
-# Resume exactly where you left off
-apex session resume <id>
 ```
-
-You never need to re-explain the codebase.
+Monday 5pm:   you close the terminal, task 70% done
+Tuesday 9am:  apex session resume <id>
+              → AI picks up exactly where it stopped, no re-explaining needed
+```
 
 ---
 
 ## Slash Commands Reference
 
-Type these inside the APEX TUI:
-
-| Command | What it does |
-|---|---|
-| `/init-apex` | Initialize workspace context and load configuration |
-| `/warm-up` | Load git status, decisions, and workspace summary |
-| `/eng.start ENG-XX` | Fetch ticket, analyze repos, produce implementation plan |
-| `/eng.plan` | Re-present or refine the current plan |
-| `/eng.work` | Execute the approved plan — writes code across all repos |
-| `/eng.pre-pr` | Run tests, lint, type check; auto-fix failures |
-| `/eng.pr` | Open one PR per repo; update issue tracker |
-| `/eng.debug` | Root-cause analysis and incident investigation |
-| `/eng.review` | Review current diff and staged changes |
-| `/eng.docs` | Update technical documentation |
-| `/qa-gate` | Run full quality gate with numeric scoring |
+| Command | Phase | What it does |
+|---|---|---|
+| `/init-apex` | Setup | Initialize workspace config and load org context |
+| `/warm-up` | Daily | Load git status, decisions, and workspace summary |
+| `/eng.start ENG-XX` | Investigate | Fetch ticket, search codebase, produce investigation |
+| `/eng.plan` | Plan | Generate phased cross-repo implementation plan |
+| `/eng.work` | Implement | Execute approved plan across all repos |
+| `/eng.pre-pr` | Validate | Tests, lint, type check, auto-fix failures |
+| `/eng.pr` | Ship | Open one PR per repo, update Linear ticket |
+| `/eng.debug` | Debug | Root-cause analysis and incident investigation |
+| `/eng.review` | Review | Review current diff and staged changes |
+| `/eng.docs` | Document | Update technical docs and READMEs |
+| `/qa-gate` | QA | Full quality gate with numeric scoring |
 
 ---
 
@@ -340,6 +351,7 @@ Type these inside the APEX TUI:
 apex                           # Open workspace selector and launch
 apex login                     # Authenticate with GitHub
 apex logout                    # Remove stored credentials
+apex auth linear               # Connect Linear via OAuth
 apex init                      # Register current repo in a workspace
 apex index                     # Index workspace repos for semantic search
 apex index --repo backend      # Index a specific repo only
@@ -350,8 +362,7 @@ apex session resume <id>       # Resume a paused session
 apex workspace list            # List all workspaces
 apex workspace edit <name>     # Add or remove repos from a workspace
 apex knowledge add <path>      # Upload docs/ADRs to org knowledge base
-apex config set <key> <value>  # Store a credential or config value
-apex config show               # Show current configuration
+apex knowledge search <query>  # Semantic search over knowledge base
 apex usage                     # Show token consumption by model/provider
 apex decisions                 # Show saved architectural decisions
 apex logs                      # Tail the latest AI engine log
@@ -360,49 +371,28 @@ apex version                   # Print version
 
 ---
 
-## Integrations
-
-| Integration | What APEX does |
-|---|---|
-| **Linear** | Fetches ticket description and ACs; updates status when PR is opened |
-| **Jira** | Fetches issue details; transitions status on PR open |
-| **GitHub** | Opens PRs; monitors CI via Checks API; push webhook for auto re-index |
-| **GitLab** | Opens merge requests; checks pipeline status |
-
-Connect them:
-
-```bash
-apex auth linear                           # OAuth flow
-apex config set github_token  ghp_...
-apex config set jira_base_url https://myorg.atlassian.net
-apex config set jira_api_token ...
-apex config set jira_email    you@company.com
-```
-
----
-
 ## Common Questions
 
-**Q: Does APEX create files in my repos?**  
-No. APEX writes code to your repos (that's the point) but creates zero configuration or state files there. All state lives in `~/.apex/` and the cloud.
+**Q: Does APEX create any files in my repos?**  
+Two files, both intentional. `/init-apex` creates `ENV.md` — a workspace environment reference that should go in `.gitignore`. It also creates `AGENTS.md` — an AI context file that should be committed to the repo so the AI understands the codebase conventions. Beyond these, no configuration, state, or lock files are ever created in your repos.
 
 **Q: Do I need to re-explain my codebase every session?**  
-No. APEX indexes your code into a semantic search index (RAG) and stores session summaries in episodic memory. Both are injected automatically on every LLM call.
+No. APEX indexes your code semantically and stores structured session summaries. Both are injected automatically into every LLM call. After months of work, APEX still knows why things were built the way they were.
 
 **Q: What if a task spans 4 repos?**  
 Register all 4 with `apex init`. APEX operates across all of them in every session. The plan, code changes, and PRs span all repos automatically.
 
-**Q: Can I use APEX without Linear or Jira?**  
-Yes. You can describe the task in plain English instead of a ticket ID:
+**Q: Can I start a task without a Linear ticket?**  
+Yes. Describe the task in plain English directly in the TUI:
 ```
 › add rate limiting to the payments API, 100 req/min per user
 ```
 
 **Q: How do I pause mid-task and resume tomorrow?**  
-Close the TUI (Ctrl+C) or type `/pause`. APEX saves a structured summary. Tomorrow, run `apex session resume <id>`.
+Close the terminal (Ctrl+C). APEX automatically generates a structured session summary. Tomorrow, run `apex session resume <id>` and the AI picks up exactly where it left off.
 
-**Q: What models are supported?**  
-Anthropic Claude, OpenAI GPT-4o, and Google Gemini. You bring your own API key. Configure separate models for planning vs. coding phases.
+**Q: What happens if a test fails during `/eng.work`?**  
+APEX auto-corrects up to 3 times per failure, trying different strategies. If it can't resolve it, it surfaces a recovery report explaining what it tried and what's blocked.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inventeer.tech/apex",
-  "version": "0.2.32",
+  "version": "0.2.33",
   "description": "AI-powered software delivery agent",
   "bin": {
     "apex": "./bin/apex"