@inventeer.tech/apex 0.2.31 → 0.2.32

package/README.md

@@ -1,8 +1,29 @@
 # @inventeer.tech/apex
 
-**AI-powered software delivery agent. From task to merged PR across multiple repos.**
+**AI-powered software delivery agent. From task description to open pull request — across multiple repos.**
 
-This is the npm wrapper for the [APEX CLI](https://github.com/Inventeer/apex). It downloads the correct pre-built binary for your platform on install.
+[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-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)
+
+---
+
+## 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.
+
+```
+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
+```
+
+**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/`.
+
+---
 
 ## Install
 
@@ -10,44 +31,391 @@ This is the npm wrapper for the [APEX CLI](https://github.com/Inventeer/apex). I
 npm install -g @inventeer.tech/apex
 ```
 
-Supports macOS (x64/arm64), Linux (x64/arm64), and Windows (x64).
+The binary is self-contained — no Go, Docker, or external runtime required.
+
+**Other install methods:**
 
-## Usage
+```bash
+# macOS — Homebrew
+brew install Inventeer/tap/apex
+
+# macOS / Linux — shell script
+curl -fsSL https://install.apex.dev | sh
+```
+
+Verify:
+
+```bash
+apex version
+```
+
+---
+
+## The Workspace Concept
+
+> This is the most important thing to understand about APEX.
+
+A **workspace** is a named group of repositories that APEX treats as a single unit. When you start a task, APEX reads, understands, and writes code across **all repos in the workspace simultaneously** — like a senior engineer who has the full stack loaded in their head.
+
+```
+workspace: payment-platform
+  ├── backend/          (Node.js API)
+  ├── frontend/         (React app)
+  └── 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
+
+**You register each repo once**, then forget about it:
+
+```bash
+cd ~/repos/backend      && apex init
+cd ~/repos/frontend     && apex init
+cd ~/repos/shared-types && apex init
+```
+
+APEX detects the git remote and technology stack automatically. All three repos are now in the same workspace.
+
+---
+
+## Full Setup Walk-through
+
+Follow these steps once to go from zero to your first AI-assisted PR.
+
+### Step 1 — Authenticate with GitHub
 
 ```bash
-# Authenticate (once per machine)
 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.
+
+### Step 2 — Configure a model provider
+
+APEX needs an LLM API key. Add at least one:
+
+```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.
+
+### Step 4 — Register your repos
+
+Run from inside each repository you want APEX to work with:
+
+```bash
+cd ~/repos/backend      && apex init
+cd ~/repos/frontend     && apex init
+```
 
-# Register your repo
-cd ~/repos/backend && apex init
+Both repos are added to the same workspace automatically (based on git remote).
 
-# Index for RAG
+### Step 5 — 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.
+
+> The TUI shows an amber warning when the index is more than 24 hours old.
+
+### Step 6 — Verify everything is working
+
+```bash
+apex doctor
+```
+
+Expected output:
 
-# Launch
+```
+✅ native runtime: built-in
+✅ model API key: anthropic configured
+✅ workspace: backend, frontend registered
+✅ gateway: connected
+```
+
+Fix any ❌ items before continuing.
+
+### Step 7 — Launch
+
+```bash
 apex
 ```
 
-## What is APEX?
+APEX opens the workspace selector and the 3-panel TUI:
 
-APEX takes a developer from a task description to open pull requests across multiple repositories — with full context awareness, episodic memory, and zero configuration files left in your repos.
+```
+╔═══════════════════════════════════════════════════════════════════════════╗
+║  APEX  ▸  payment-platform                                   v0.2.30     ║
+╠══════════════════╦════════════════════════════════╦════════════════════════╣
+║  Workspace       ║                                ║  Live Diff             ║
+║  ──────────────  ║   APEX                         ║  ────────────────────  ║
+║  • backend       ║   Workspace ready:             ║  backend/              ║
+║  • frontend      ║   › 2 repos indexed            ║   src/payments/        ║
+║  • 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  ║
+╠══════════════════╩════════════════════════════════╩════════════════════════╣
+║  ›  _                                                                     ║
+╚═══════════════════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## The Delivery Workflow
+
+Once APEX is running, this is the typical sequence for any engineering task:
+
+### `/init-apex`  ·  Initialize the workspace
+
+```
+/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.
+
+---
+
+### `/warm-up`  ·  Load context before starting
 
 ```
-apex /eng.start TASK-456
+/warm-up
 ```
 
-The AI fetches the ticket, investigates all workspace repos, proposes a cross-repo plan, and executes it step by step. When you close the terminal, the session is summarized. Next time, APEX resumes in under 500 tokens of overhead.
+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.
+
+---
+
+### `/eng.start ENG-XX`  ·  Investigate and plan
+
+```
+/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
+
+You review the plan and press:
+
+```
+  [ A ] Approve   [ E ] Edit   [ C ] Cancel
+```
+
+---
+
+### `/eng.work`  ·  Execute the plan
+
+```
+/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.
+
+You can watch, or come back when it's done.
+
+---
+
+### `/eng.pre-pr`  ·  Validate before opening PRs
+
+```
+/eng.pre-pr
+```
+
+APEX runs a full quality gate across all repos:
+- Unit and integration tests
+- Type checking
+- Lint
+- Cross-repo dependency validation
+
+Any failures are auto-fixed. You get a quality report with a pass/fail score.
+
+---
+
+### `/eng.pr`  ·  Open pull requests
+
+```
+/eng.pr
+```
 
-**What runs locally**: the `apex` binary, a native in-process AI runtime engine, and your repos.  
-**What lives in the cloud**: codebase RAG, episodic session memory, org config, LLM proxy with context injection.
+APEX opens **one PR per repo**, each containing:
+- 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
+
+---
+
+## 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
+
+# Resume exactly where you left off
+apex session resume <id>
+```
+
+You never need to re-explain the codebase.
+
+---
+
+## 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 |
+
+---
+
+## CLI Reference
+
+```bash
+apex                           # Open workspace selector and launch
+apex login                     # Authenticate with GitHub
+apex logout                    # Remove stored credentials
+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
+apex index --full              # Force full re-index (clears previous)
+apex doctor                    # Run pre-flight health checks
+apex session list              # List paused sessions
+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 usage                     # Show token consumption by model/provider
+apex decisions                 # Show saved architectural decisions
+apex logs                      # Tail the latest AI engine log
+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: 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.
+
+**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:
+```
+› 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>`.
+
+**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.
+
+---
 
 ## Links
 
-- [Homepage](https://github.com/Inventeer/apex)
+- [GitHub](https://github.com/Inventeer/apex)
 - [Documentation](https://github.com/Inventeer/apex/tree/main/docs)
+- [Get Started Guide](https://github.com/Inventeer/apex/blob/main/docs/get-started.md)
 - [Releases](https://github.com/Inventeer/apex-releases/releases)
-- [Issues](https://github.com/Inventeer/apex/issues)
+- [Issues & Feedback](https://github.com/Inventeer/apex/issues)
+
+---
 
 ## License
 
-MIT
+MIT © [Inventeer](https://github.com/Inventeer)

package/package.json

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