codebase-onboarder 0.6.0 → 1.0.0

package/README.md

@@ -3,7 +3,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org/)
 [![Zero Dependencies](https://img.shields.io/badge/runtime%20dependencies-0-success.svg)](package.json)
-[![Tests](https://img.shields.io/badge/tests-560%20passing-brightgreen.svg)](tests/)
+[![Tests](https://github.com/Amitpandey88/onboarder/actions/workflows/ci.yml/badge.svg)](https://github.com/Amitpandey88/onboarder/actions/workflows/ci.yml)
 
 > **Drop a path. Get a map.**  
 > A lightweight, zero-dependency codebase visualizer and architectural map generator that runs entirely on your local machine.
@@ -12,7 +12,7 @@
 
 Onboarder reads a software repository the way a senior engineer would: starting at the front door, tracing import graphs, mapping architectural layers, computing risk/health metrics, discovering dead exports and dependency drift, and charting Git hotspots — rendering everything as interactive, zoomable diagrams.
 
-**100% Local & Private**: Your code never leaves your computer. No external services or accounts are required.
+**Local analysis**: Repository maps and the offline explorer run on your machine without an account. Optional AI chat sends task context and requested source to your configured model provider.
 
 ---
 
@@ -22,9 +22,12 @@ Onboarder reads a software repository the way a senior engineer would: starting
 # Install from npm (Node 20+, zero runtime dependencies)
 npm install -g codebase-onboarder
 
-# Explore the repo you are standing in, right in your terminal
+# Open the repository chat harness in your terminal
 onboarder
 
+# Browse offline, including folders and Git URLs
+onboarder explore
+
 # …or start the web UI instead
 onboarder start
 ```
@@ -34,13 +37,14 @@ Or from source:
 ```bash
 git clone https://github.com/Amitpandey88/onboarder.git
 cd onboarder
+npm ci
 npm start
 ```
 
 Open **http://localhost:4310** in your browser (the CLI opens it for you).
 
-- **Two front doors, one engine.** `onboarder` opens an interactive terminal session; `onboarder start` opens the web UI. Both run the *same* analyzer, so they can never disagree about a repository.
-- **Zero build steps**: Native ES modules.
+- **Chat, explorer, and web UI.** `onboarder` opens the Hermes chat harness; `onboarder explore` opens offline browsing; `onboarder start` opens the web UI. Repository analysis uses the same engine in all three.
+- **Ready to run from npm**: Compiled JavaScript is included in the package. Application source lives in `src/` as TypeScript. Run `npm run build` after editing it, or use `npm run dev` for automatic rebuilds and server restarts.
 - **Zero runtime dependencies**: Powered by Node.js built-ins (`node:http`, `node:fs`, `node:crypto`).
 - **Offline ready**: Vendored Mermaid.js and Monaco Editor builds are included in `public/vendor/`.
 
@@ -48,23 +52,87 @@ Open **http://localhost:4310** in your browser (the CLI opens it for you).
 
 ## 🖥️ The terminal app
 
-Type `onboarder` in any repo and you get the website, in your terminal. No server, no browser, no network — it reads the folder directly.
+Type `onboarder` to open the Hermes-powered chat interface for the current repository, or `onboarder chat ~/work/some-repo` to open another local checkout. An amber welcome screen shows the actual configured model, repository, permissions, six workflow skills, and 37 registered tools. The composer has a session status bar with recorded token usage, elapsed run time, and live tool activity. It keeps terminal scrollback and loads the browsing engine only when requested.
+
+```sh
+onboarder chat
+onboarder chat ~/work/some-repo --mode review
+onboarder chat https://github.com/owner/repo
+onboarder chat --resume <conversation-id>
+```
+
+Inside the chat:
+
+```text
+codebase ask › /model configure
+codebase ask › /repo https://github.com/owner/repo
+codebase ask › Explain how authentication works
+codebase ask › Where are those permissions checked?
+codebase ask › /review 42 Focus on correctness and security
+codebase review › /triage 12
+codebase triage › /permissions checks on
+codebase triage › /implement Fix the bug described in issue 12
+codebase implement › /diff
+codebase implement › Add a regression test for that fix
+codebase implement › /history
+```
+
+| Commands | Purpose |
+| --- | --- |
+| `/ask`, `/review`, `/triage`, `/implement`, `/pr`, `/github` | Start a workflow; following messages continue it |
+| `/mode`, `/model`, `/permissions`, `/limits` | Control the workflow, provider, allowed actions, timeout, and turn budget |
+| `/map`, `/tree`, `/find`, `/show`, `/diff`, `/health`, `/rescan` | Browse and analyze offline; inspect the active implementation workspace |
+| `/tour`, `/explain`, `/deps`, `/inspect`, `/graph`, `/blast`, `/symbols` | Follow the reading order, inspect modules, and trace dependencies |
+| `/hubs`, `/layers`, `/patterns`, `/stats`, `/security`, `/stack`, `/entry`, `/externals`, `/coupling`, `/clusters`, `/risks` | Explore repository structure, health, and risks |
+| `/log`, `/hotspots`, `/blame`, `/diagram`, `/layers-diagram`, `/atlas`, `/docs`, `/workflows`, `/sbom` | Inspect Git history, diagrams, documentation, CI, and licenses |
+| `/engines`, `/deep`, `/web`, `/about` | Discover and run optional analyzers, start the web interface, and inspect repository details |
+| `/new`, `/history`, `/resume`, `/repo`, `/status` | Manage saved conversations, repository context, and workspaces |
+| `/clone <GitHub URL>`, `/pull` | Clone a GitHub repository and refresh a clean saved checkout |
+| `/paste`, `/send`, `/discard` | Compose or discard multiline prompts and code |
+| `/setup`, `/doctor`, `/help`, `/clear`, `/cancel`, `/exit` | Set up Hermes, check readiness, and control the terminal session |
+| `/tools`, `/skills`, `/runs`, `/run`, `/export` | Inspect actual capabilities, saved runs, and export this chat as Markdown |
+
+Typing `/` immediately opens a searchable command menu with descriptions. Keep typing to filter, use ↑/↓ to choose, and press Tab or Enter to fill the command without starting a task. A fully typed command executes on Enter. Esc dismisses the menu and restores normal history navigation. Tab also completes settings and indexed file paths. Alt-Enter adds a newline; bracketed paste keeps multiline code together and waits for Enter before sending. Ctrl-A/E move to the start/end, Ctrl-U clears the draft, and Ctrl-C cancels an active task. Ctrl-D cancels, saves, and exits when the draft is empty.
+
+Chat opens in a **full-screen terminal interface** with the composer pinned to the bottom. The welcome, conversation and menus automatically reflow when the terminal window changes size. **Page Up / Page Down** scroll the conversation without editing your draft; new output preserves your reading position until you return to the latest messages. Narrow or short windows use compact layouts, and the original Onboarder **code-compass** logo appears in full or compact terminal art. Its reusable vector image is [public/assets/onboarder-mark.svg](public/assets/onboarder-mark.svg).
+
+The screen paints only changed rows and batches streamed output. Drafts survive resizes and model-wizard handoffs, and leaving chat restores the original shell screen. The in-memory viewport retains up to 4,000 logical lines or 2 MiB; conversation storage and `/export` remain available separately. Follow-ups reuse the saved Hermes session and its isolated implementation workspace. Changing the workflow, PR/issue target, model, or permissions starts a new session. `/clear` clears the screen while keeping context; `/new` resets the conversation. Checks and GitHub writes default to off. `/deep` requires checks permission. `/pr` prepares changes locally unless GitHub writes are enabled; publishing must also be requested in the task. `/export` saves a private Markdown transcript under the agent home's `exports` folder.
+
+`/model` opens a Hermes-style provider/model picker below the input. Type to filter, use ↑/↓ to select, and press Enter to choose. Available providers and models come from the installed Hermes catalog; selection uses Hermes' own credential resolution and saves the model to the dedicated Onboarder profile. Escape keeps your current model and conversation. Choose **Configure provider / authentication**, or run `/model configure`, for the full official Hermes configuration, including custom endpoints and provider login. Older Hermes installations can use this full wizard when the quick picker is unavailable. No model names or provider credentials are hardcoded into the picker.
+
+At startup, an unconfigured profile offers **Choose a provider and model** or **Continue offline**. Configured profiles start directly in chat. Hermes must be installed separately for AI tasks; offline commands work without it. Conversation summaries are stored privately in `~/.config/onboarder/agent/chats`, alongside agent runs, and known environment credentials are redacted. `/resume` requires a conversation for the current repository and preserves your current permission choices. `onboarder chat --resume` takes a **conversation ID**; `onboarder agent … --resume` takes an **agent run ID**.
+
+To ask about a GitHub repository, launch `onboarder chat https://github.com/owner/repo`, use `/repo <URL>` or `/clone <URL>`, or simply paste the URL into chat. You can also paste `<URL> Explain this repository` to clone and ask in one message. HTTPS and GitHub SSH URLs work; private repositories use your existing Git credentials. Cloning shows progress and can be cancelled with Ctrl-C.
+
+Chat checkouts are saved under `~/.config/onboarder/agent/repositories` and remain after exit, so conversations and isolated implementation workspaces can resume. Reopening the same URL reuses its checkout. `/pull` fetches current changes with a fast-forward-only pull and refuses local changes; use `/new` first if an implementation workspace is active. A successful pull resets AI context so the next question reads the updated source. To resume later, reopen the same URL and use `/history`, then `/resume <conversation-id>`.
+
+The original explorer remains available for its full browsing, source picker, diagrams, and optional analyzer commands:
 
 ```bash
-onboarder                 # explore the current directory
+onboarder explore         # choose a source; Enter uses the current directory
 onboarder explore ~/work/some-repo
-onboarder --server        # force the web UI (what bare `onboarder` used to do)
+onboarder report .        # one-shot summary, no interactive terminal needed
+onboarder report . --json # stable JSON for scripts and CI
+onboarder --server        # force the web UI
 ```
 
-It lands on a `map` of the repo, then waits:
+The explorer lands on a `map` of the repo, then waits:
 
 ```
   codebase > tour
   codebase > hotspots
   codebase > find resolveImport
   codebase > deps logger.js
+  codebase > inspect logger.js      # one file’s links, exports, and findings
   codebase > blast pathUtil.js      # what breaks if this breaks
   codebase > github                # what GitHub says about this repo
+  codebase > workflows             # CI triggers, jobs, and steps
+  codebase > sbom express           # dependency and license inventory
+  codebase > diff HEAD~1 HEAD      # changes and dependent-file impact
+  codebase > engines               # optional deep analyzers on this machine
+  codebase > deep gitleaks          # run one analyzer when requested
+  codebase > ask Where should I start? # optional AI answer with scan context
+  codebase > pick                  # choose another local folder or Git URL
   codebase > !git log --oneline -3  # shell, without leaving
   codebase > exit
 ```
@@ -72,16 +140,107 @@ It lands on a `map` of the repo, then waits:
 | | |
 |---|---|
 | **map · tour · explain** | What this is, the reading order for a new teammate, and a file or folder explained in prose |
-| **tree · find · show · deps** | Browse it, search it, read it, and trace what it connects to |
+| **tree · find · show · inspect · deps** | Browse, search, read, inspect, and trace files |
 | **graph · blast · symbols** | The dependency tree as arrows, the transitive blast radius, and a file's outline |
 | **health · hubs · layers · patterns** | The analysis, in the same words the site uses |
 | **coupling · clusters · risks** | Folder traffic as a heat grid, module groups, and everything wrong in one list |
 | **log · hotspots · blame** | Git history, the files that are complex *and* often changed, and who wrote a line |
-| **diagram · docs** | Real Mermaid source, and prose you can print or write to `ONBOARDER.md` |
-| **cd · rescan · web** | Switch repo, reload from disk, or start the web UI without leaving |
+| **diagram · atlas · docs** | Mermaid source, a diagram index, and prose you can print or write to `ONBOARDER.md` |
+| **workflows · sbom · diff** | CI pipelines, dependency/license inventory, and changed files with blast radius |
+| **engines · deep** | See optional analyzers, then run one (`deep semgrep`) or all (`deep all`) |
+| **ask** | Ask an OpenAI-compatible model a question using the current repository scan |
+| **pick · cd · rescan · web** | Browse device folders, switch repo, reload from disk, or start the web UI |
 | **github** | Stars, forks, watchers, license and topics from GitHub, for the repo you have loaded |
 | **Tab · `!cmd`** | Completes commands then file paths; runs a shell command inline |
 
+`report` reads a local folder or Git URL once, prints file counts, import resolution,
+entry points, health, security, and test reachability, then exits. Its JSON output
+has `schemaVersion: 1` and contains no source text.
+
+All application modules are authored in TypeScript under `src/`: the server,
+MCP tools, analyzer, diagrams, CLI, and browser views. Builds emit JavaScript,
+declarations, and source maps into the existing runtime folders, so the npm CLI
+and Node 20+ keep their existing entry points. Edit `src/`, rather than generated
+files in `cli/`, `server/`, `shared/`, or `public/js/`.
+
+```bash
+npm ci
+npm run dev        # rebuild on changes; restart after a successful compilation
+npm run build      # typecheck and generate the distributable files
+npm run check      # typecheck, tests, and generated-build consistency
+```
+
+`tsconfig.json` checks the whole application. The new portable contracts, scan
+controls, request validator, browser adapter, editor wrapper, and terminal layout
+also pass the strict checks in `tsconfig.strict.json`. Older view and orchestration
+code still uses permissive types; converting every legacy callback and data bag
+to strict types is follow-up work. No application file disables type checking.
+
+Scans accept validated limits and bounded read concurrency. The browser offers a
+**Cancel scan** button, browser-folder scans report progress, and disconnected
+server requests stop scanning. File limits measure UTF-8 bytes, including
+non-ASCII source. TypeScript configs support comments, trailing commas, slash
+aliases, and mapping generated JavaScript imports back to TypeScript source. CLI limits work with `report` and persist across `explore` rescans and repository changes:
+
+```bash
+onboarder report . --max-files 10000 --max-file-size 524288 --read-concurrency 4
+```
+
+The HTTP equivalent is `{ "path": "/repo", "options": { "maxFiles": 10000,
+"maxFileSize": 524288, "readConcurrency": 4 } }`. Defaults are 4,000 files,
+200 KiB per file, and 8 concurrent reads. Maximums are 100,000 files, 10 MiB,
+and 32 reads. Scan cache keys include every file and its imports, exports, and
+findings, so changes beyond the first hundred files also invalidate the cache.
+
+The explorer's `ask` command is optional. Set `ONBOARDER_AI_BASE_URL` and `ONBOARDER_AI_MODEL`, plus
+`ONBOARDER_AI_API_KEY` when the endpoint requires a key. The CLI also accepts
+`OPENAI_BASE_URL`, `OPENAI_MODEL`, and `OPENAI_API_KEY`. It sends the question
+and a limited scan summary only when you run `ask`; the key stays in the
+process environment and is not saved in Onboarder's config.
+
+### Hermes repository and GitHub agent
+
+`onboarder agent` adds multi-step repository work through [Nous Research's Hermes Agent](https://github.com/NousResearch/hermes-agent). Hermes is an optional, separately installed Python runtime; Onboarder's npm package still has no runtime dependencies. The TypeScript harness supplies **37 scoped MCP tools** built around Onboarder's existing analysis and GitHub's API.
+
+```sh
+onboarder agent setup
+onboarder agent model                 # choose a provider/model in the dedicated profile
+onboarder agent doctor
+onboarder agent ask . --task "Explain the authentication flow"
+onboarder agent review . --pr 42 --task "Review correctness and security"
+onboarder agent triage . --issue 12 --task "Investigate the cause and propose labels"
+onboarder agent implement . --issue 12 --task "Fix this issue" --allow-checks
+onboarder agent pr . --task "Implement the fix and open a draft PR" --allow-checks --allow-github-writes
+onboarder agent github . --task "Explain why the latest CI run failed"
+onboarder agent runs
+onboarder agent show <run-id>
+```
+
+The same commands work inside the explorer: `agent review --pr 42` uses the loaded repository. Implementation and PR work require a persistent local checkout; the explorer's temporary URL clones are removed on exit. `agent help` lists setup and workflow options. Use `--dry-run --json` to inspect a plan without creating a workspace or calling a model. Use `--json` for one machine-readable result; progress stays on stderr.
+
+| Workflow | Result |
+| --- | --- |
+| `ask` | Repository Q&A grounded in scan, architecture, search and source tools |
+| `review` | Local-change or GitHub PR findings, patch coverage, discussion and checks at the PR head SHA |
+| `triage` | Issue investigation, duplicate candidates, priority, labels and a proposed implementation plan |
+| `implement` | Edits in a separate Git worktree, diff inspection and optional npm checks |
+| `pr` | Implementation plus a proposed PR; publishes a **draft** when GitHub writes are enabled |
+| `github` | Repository, issues, PR discussions, labels, CI runs/jobs, comments and review tasks |
+
+GitHub access uses the local checkout's **github.com `origin`** and `GITHUB_TOKEN` or `GH_TOKEN`. Public reads can work without a token; private reads and writes need a token with access to the requested resources. Git transport uses your existing Git credentials. Publishing a review requires the freshly read PR head SHA and refuses a changed head.
+
+Source editing is available only in `implement`/`pr` worktrees created at **committed HEAD** on a `codex/agent-…` branch. Uncommitted changes in your source checkout are excluded. File tools refuse symlinks, credential files, traversal and files larger than 128 KiB; edits require the hash of a fresh read. Workspaces remain available after completion or failure for inspection. Publishing commits workspace changes, pushes that task branch and creates a draft PR; it does not merge. The PR target defaults to the cached `origin/HEAD` branch, falling back to the current branch; choose another with `--base`. Repeated identical successful writes are deduplicated within one running tool server.
+
+`--allow-checks` allows lockfile dependency installation with lifecycle scripts disabled, plus `npm test`, `npm run typecheck` and `npm run build`. Test/build scripts can execute repository code and may write files. `--allow-github-writes` enables issue updates, comments, PR reviews and draft PR publishing. Both permissions are enforced by the tools and default to off. Onboarder supplies only its dedicated MCP toolset to Hermes.
+
+Runs have a default 24-turn, 300-second limit; adjust with `--max-turns` and `--timeout`. Ctrl-C cancels an active agent in both the CLI and explorer. `--resume <run-id>` continues a saved Hermes session in its original workspace; repeat any enabled permission flags. Resume cannot expand the original permissions. Timeouts, missing completion frames and nonzero process exits are recorded as failures.
+
+Run metadata, final answers and operation audits live under `~/.config/onboarder/agent` (override with `ONBOARDER_AGENT_HOME`). Hermes configuration and transcripts use a dedicated named profile under the installation's `profiles` folder; `agent setup` prints its path. Audit records contain operation names, outcome and timing; Hermes session transcripts can contain prompts and source. Repository/tool content is sent to the configured model during agent tasks. Known environment credentials are redacted from Onboarder diagnostics and final answers. API keys supplied through the environment are not written by Onboarder.
+
+For an existing compatible endpoint, set `ONBOARDER_AI_BASE_URL`, `ONBOARDER_AI_MODEL` and optionally `ONBOARDER_AI_API_KEY` **before the first `agent setup`**. Standard `OPENAI_BASE_URL`, `OPENAI_MODEL`, `OPENAI_API_KEY` aliases also work. Later, `agent model` updates the dedicated profile without changing your normal Hermes profile. Use `ONBOARDER_HERMES_BIN` to select a Hermes executable. For a nonstandard source installation, preserve its `HERMES_HOME`/`HERMES_RUNTIME_DIR` environment so the harness can locate its shared Python packages.
+
+`onboarder agent source` fetches the official MIT-licensed source at the researched revision into the agent source cache. This does not install Python dependencies or vendor Hermes into the npm package. The source review and integration decisions are documented in [Hermes research](docs/HERMES_RESEARCH.md). Developers can run `node scripts/hermes-smoke.mjs` after building to verify a real installed Hermes runtime against a local model fixture, without external inference or GitHub writes.
+
 **It also takes a GitHub URL, the way the site does.** Point it at one and it clones, scans and opens that repo:
 
 ```
@@ -104,6 +263,7 @@ Details worth knowing:
 - **Fits your terminal.** Every line is fitted to the current width and re-fits on resize; prose wraps instead of running off the edge. `NO_COLOR` and `COLUMNS` are honored.
 - **It refuses to hang.** Without a TTY, `onboarder explore` explains itself and exits rather than waiting for input that will never come. Scripts and CI keep working.
 - **Bridges to the web.** `web` starts the UI in the background and prints the URL, without ending your session.
+- **Interactive source picker.** `pick` or a bare `cd` lists device folders, supports parent/home navigation and paging, and accepts pasted paths or Git URLs. A failed load leaves the current repository open.
 
 ---
 
@@ -118,6 +278,72 @@ Details worth knowing:
 
 ## 🔍 Features & Views
 
+### Change Review — a local review workbench
+
+After opening a repository by its local path, the **Review** tab is the first
+workspace. Choose working-tree changes (including untracked files), staged
+changes, or a branch/commit range, then select **Run review**.
+
+- Security and quality patterns are flagged on **added lines**, with file and
+  line references, severity, and suggested next steps. Credential excerpts are
+  redacted from reports, including other findings on the same credential line.
+- A risk-sorted walkthrough groups source, tests, documentation, dependencies,
+  and configuration changes. Dependency impact uses the last repository scan;
+  rescan after structural edits and treat branch-range impact as an estimate.
+- The checklist reports high-severity patterns, conflict markers, test-file
+  changes, change size, and skipped files. Tests are **not executed** and
+  test-file changes do not establish coverage.
+- Filter findings, acknowledge them locally, and export Markdown or JSON.
+  Acknowledgements belong to an exact comparison fingerprint; editing the
+  change starts a fresh review. Exports always include all detected findings.
+- An optional **reviewer's brief** sends the report to your configured AI
+  provider for a summary and testing plan. It does not send the raw diff.
+  Core reviews work offline without an API key.
+
+The same review is available to scripts:
+
+```bash
+onboarder review .
+onboarder review . --staged --json
+onboarder review . --base main --head feature/my-change
+onboarder review . --profile focused --fail-on high
+```
+
+`--fail-on` exits with status 1 for findings at or above the selected severity.
+Conflict markers also return 1. Invalid comparisons return a failure instead
+of falling back to a different diff. Reviews use the Git repository root;
+subfolder scans cannot read changes outside the scanned folder.
+
+Optional `.onboarder-review.json` in the repository root:
+
+```json
+{
+  "profile": "balanced",
+  "exclude": ["dist/**", "**/*.generated.ts"],
+  "instructions": [
+    { "path": "src/auth/**", "instruction": "Check permission boundaries and failure handling." }
+  ]
+}
+```
+
+Profiles: `focused` includes medium/above, `balanced` low/above, and `thorough`
+all patterns. Exclusions use `*`, `**`, and `?` path globs. Guidelines are shown
+for human review and included in the optional AI brief; the pattern engine
+does not claim to enforce natural-language guidelines. Configuration always
+comes from the current working tree, including for staged and branch reviews.
+This project's configuration excludes generated JavaScript and vendored files
+so changes are reviewed in their canonical TypeScript source.
+
+Git commands have a 15-second timeout and a 5 MB output limit. Working reviews
+include at most 200 untracked files, each at most 1 MB; oversized inputs fail
+explicitly. Binary content, deleted files, metadata-only changes, exclusions,
+and untracked symlinks have visible skip reasons. Reviews can be canceled.
+
+Inspired by CodeRabbit's change summaries, path guidelines, and pre-merge
+checks, this is a local pattern review workflow. It does not install a GitHub
+App, automatically post PR comments, apply fixes, execute repository scripts,
+or replace a human/security review.
+
 ### 1. Explorer (One Canvas, 6 Modes)
 - **Tree**: Hierarchical expandable cell map of directories, files, hubs, and entry points with ghost connection cells.
 - **Files**: Intra-folder dependency graphs with deep-dive call inspections.
@@ -128,6 +354,17 @@ Details worth knowing:
 - **Tour**: Curated step-by-step walkthrough of key architectural waypoints.
 - **Atlas**: Grid gallery of every pre-generated diagram across folders and components.
 
+**Search:** Click Search or press `Cmd/Ctrl+K` to find files, symbols, and file
+contents. Arrow keys select results; Enter opens them and `Cmd/Ctrl+Enter`
+opens the source. `Alt+Left/Right` switches result kinds. Tab moves between
+dialog controls; Escape clears the query, then closes. Filters such as
+`path:src ext:ts render` can be removed using their chips.
+
+Search reuses the scan's symbol index, combines rapid keystrokes, and displays
+bounded previews with exact local match counts. Graph animation pauses outside
+the Graph tab, while search is open, and when the browser tab is hidden. Review
+filters update the findings without rebuilding the surrounding workspace.
+
 ### 1b. Deep Analysis — plug in the best engines (Optional, self-hosted)
 
 Onboarder is the **frontend**; the sharpest open-source analyzers are the
@@ -167,8 +404,8 @@ Next to **Explorer** in the top nav. One page with everything:
 - **What this means** — the AI reads the report: *"Explain this analysis"* for a
   prioritised read, or ask about a specific finding (*"is the eval finding
   reachable?"*). It is told which engines did **not** run, so it will not claim
-  coverage it does not have. Needs an OpenAI-compatible endpoint; without one the
-  report is still fully readable and the button offers the API key drawer.
+  coverage it does not have. Needs a Hermes connection or an AI endpoint; without one the
+  report is still fully readable and the button offers the AI connection drawer.
 
 Rules that keep this safe to self-host:
 
@@ -202,8 +439,12 @@ Rules that keep this safe to self-host:
 
 ### 5. AI Notes & Explainers (Optional)
 - Works 100% offline out-of-the-box.
+- In **AI connection**, choose **Hermes · use my configured login** to reuse the Onboarder CLI's Hermes provider and model. No API key is needed in the browser. The drawer shows the current model/provider; use **Test connection**, then **Save**. Install Hermes on the computer running the server and run `onboarder agent model` to sign in or change models, then refresh the configuration in the drawer.
 - Connect any OpenAI-compatible LLM endpoint (OpenAI, Azure OpenAI, Groq, OpenRouter, Ollama, LM Studio) to generate streaming explanations and repository documentation.
-- API keys are stored solely in your browser's `localStorage` and never logged or written to disk.
+- Hermes powers questions, explanations, diagrams, documentation, analysis summaries and review briefs using their supplied repository context. Web explanations have no machine tools. Each request starts a fresh conversation, with a two-minute runtime budget and at most two concurrent requests; closing or cancelling an answer stops its Hermes process. Runtime startup can add a few seconds to the first response.
+- **AI sketch** draws the current map, folder, file or architecture view using that connection. Sketches are checked with Mermaid before they are cached and displayed. **Static** returns to the original map; **AI sketch ✓** restores the cached sketch. Generated diagrams support **Copy Mermaid**, **Save SVG**, pan/zoom and file links. **Cancel sketch**, changing views, or opening another repository cancels an unfinished request. Hermes diagram requests use low reasoning without changing the saved chat configuration.
+- Hermes owns its login and may save prompts/source in its session transcripts. Context is sent to the configured provider under its normal account usage limits. Existing API endpoint settings still work; API-mode keys are saved in browser `localStorage` and never logged or written to the server's disk. Hermes requests do not forward these browser keys.
+- Developers can run `node scripts/hermes-web-smoke.mjs` after building to verify the HTTP integration against a real installed Hermes runtime and a local model fixture without external inference.
 
 ### 6. MCP Server — let any AI agent onboard itself
 
@@ -375,43 +616,29 @@ Cloudflare quick tunnels and Tailscale remain supported. They terminate TLS and
 
 ```
 codebase-onboarder/
-├── bin/             # npm entry point (shebang trampoline) & postinstall note
-├── cli/             # Onboarding wizard, config commands, doctor, tunnels
-│   ├── main.js      # argv → command; bare `onboarder` picks explorer vs server
-│   ├── ui.js        # Terminal paint; --no-color / NO_COLOR strip it in one place
-│   └── explorer/    # The terminal app
-│       ├── app.js     # The readline session, TTY guards, `web` bridge
-│       ├── session.js # Loads a repo exactly as POST /api/scan does
-│       ├── views.js   # The site's screens, drawn as text (pure functions)
-│       └── commands.js# One command table: dispatch, help, and tests share it
-├── server/          # Zero-dependency Node.js HTTP server
-│   ├── index.js     # createServer / startServer / startup banner
-│   ├── config.js    # Settings schema, normalization, atomic 0600 writes
-│   ├── pidfile.js   # PID + run record (mode, url, log) for status / stop / restart
-│   ├── daemon.js    # Detached background start, log file, readiness probe
-│   ├── startup.js   # Login items: launchd plist / systemd --user unit / Startup folder
-│   ├── logger.js    # Aligned-text or JSON log lines from one entry shape
-│   ├── layout.js    # Shared terminal geometry: width, fit, panel, resize
-│   ├── router.js    # Route table, live per-request settings, auth & CSRF gates
-│   ├── auth.js      # Signed HttpOnly browser sessions
-│   ├── apiAuth.js   # Login/status/logout endpoints
-│   ├── apiSettings.js# GET/PUT /api/settings, key rotation
-│   ├── tunnel.js    # Cloudflare & Tailscale status/commands
-│   ├── https.js     # Caddy config, ACME/TLS readiness & lifecycle
-│   ├── httpGuards.js# Host verification & CSRF/rebinding guards
-│   ├── apiScan.js   # Local & remote scan coordination
-│   ├── apiFile.js   # Path-traversal safe file serving
-│   ├── gitHistory.js# Local Git log parser & hotspot metrics
-│   └── sessions.js  # Temporary clone lifecycle manager
-├── shared/          # Isomorphic analyzer engine (Runs in Node & Browser)
-│   ├── analyzer/    # Language parsers, graph analytics, metrics, security
-│   └── diagram/     # Mermaid diagram generation
-├── public/          # Frontend client application
-│   ├── js/          # Vanilla ES modules (State, Inspector, Views, Settings)
-│   ├── vendor/      # Vendored Mermaid & Monaco Editor (Offline)
-│   ├── index.html   # Main application interface
-│   └── login.html   # Self-hosted access-key sign-in
-└── tests/           # Comprehensive node:test suite
+├── src/                  # Canonical TypeScript application source
+│   ├── cli/              # Wizard, lifecycle commands, terminal explorer, reports
+│   ├── server/           # HTTP server, auth, settings, clone sessions, MCP, tools
+│   ├── shared/           # Portable contracts and the isomorphic analysis engine
+│   │   ├── contracts.ts  # FileSource, scan options/progress, settings, analysis types
+│   │   ├── analyzer/     # Language parsers, graph analytics, scan controls, metrics
+│   │   ├── diagram/      # Mermaid and AI diagram generation
+│   │   └── search/       # Shared query language
+│   └── public/           # Browser application, views, components, integration types
+├── bin/                  # npm entry-point trampoline and postinstall note
+├── cli/                  # Generated terminal runtime and declarations
+├── server/               # Generated server/MCP runtime and declarations
+├── shared/               # Generated shared engine, served at /shared/
+├── public/
+│   ├── app.js & js/      # Generated browser ES modules
+│   ├── vendor/           # Offline Mermaid and Monaco builds
+│   ├── index.html        # App shell and scan controls
+│   ├── login.html        # Self-hosted access-key sign-in
+│   └── styles.css        # Existing paper-and-ink design
+├── scripts/              # Development watcher and build consistency verification
+├── tsconfig.json         # Whole-application compilation
+├── tsconfig.strict.json  # Strict core checks
+└── tests/                # Native node:test regression suite
 ```
 
 ---
@@ -421,7 +648,10 @@ codebase-onboarder/
 Onboarder includes a comprehensive automated test suite built with Node's native test runner:
 
 ```bash
-# Run all 565 tests
+# Run all checks (also exercised in CI on Node 20, 22, and 24)
+npm run check
+
+# Run the regression suite
 npm test
 ```
 
@@ -433,6 +663,7 @@ Test suites cover:
 - The settings layer end to end: schema validation, atomic config writes, the
   Bearer auth gate, key rotation, DNS-rebinding protection, and the wizard's
   branching/flag logic.
+- Scan cancellation, bounded concurrent reads, UTF-8 limits, and request validation.
 - Deep Analysis tooling: engine detection across Windows/macOS/Linux, install-plan
   validation, output parsing, and report shaping.
 

package/bin/build-if-source.js

@@ -0,0 +1,23 @@
+// Source checkouts need compilation; published npm installs already contain it.
+import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const root = fileURLToPath(new URL('../', import.meta.url));
+if (existsSync(path.join(root, 'src')) && existsSync(path.join(root, 'tsconfig.json'))) {
+  const compiler = path.join(root, 'node_modules/typescript/bin/tsc');
+  if (!existsSync(compiler)) {
+    console.error('Run npm ci to install the TypeScript development tools before starting from source.');
+    process.exitCode = 1;
+  } else {
+    for (const args of [
+      ['-p', 'tsconfig.json', '--noEmit'],
+      ['-p', 'tsconfig.strict.json'],
+      ['-p', 'tsconfig.json'],
+    ]) {
+      const result = spawnSync(process.execPath, [compiler, ...args], { cwd: root, stdio: 'inherit' });
+      if (result.status !== 0) { process.exitCode = result.status || 1; break; }
+    }
+  }
+}

package/cli/agent/command.d.ts

@@ -0,0 +1,71 @@
+export declare const AGENT_HELP = "\n  Onboarder agent \u2014 Hermes with repository and GitHub tools\n\n  onboarder agent setup                    Create a dedicated Hermes profile\n  onboarder chat [folder]                  Open the conversational harness with / commands\n  onboarder agent model                    Configure its model/provider interactively\n  onboarder agent doctor                   Check runtime and integration compatibility\n  onboarder agent source                   Fetch the researched official Hermes source\n  onboarder agent runs                     List saved runs\n  onboarder agent show <run-id>             Inspect a saved result and workspace\n  onboarder agent <workflow> [folder] --task \"...\"\n\n  Workflows: ask, review, triage, implement, pr, github\n  --pr <number>             Review/inspect a GitHub pull request\n  --issue <number>          Work from an issue\n  --base <branch>           PR target (default: origin HEAD, or current branch)\n  --allow-checks            Allow npm install/test/typecheck/build (repository code)\n  --allow-github-writes     Allow issue/review/comment updates and draft PR publishing\n  --max-turns <1\u2013100>       Agent turn limit (default: 24)\n  --timeout <seconds>       Run limit, 15\u20133600 (default: 300)\n  --model <name> --provider <name>  Override the dedicated Hermes model\n  --resume <run-id>         Continue a session; repeat allowed permission flags\n  --dry-run                Print the plan without a model call or worktree\n  --json                   One JSON result; progress goes to stderr\n\n  implement/pr use a new Git worktree at committed HEAD. Uncommitted source\n  changes are excluded. Without --allow-github-writes, pr prepares a draft locally.\n  GitHub uses the checkout's github.com origin and GITHUB_TOKEN or GH_TOKEN.\n  Hermes is an optional separate Python runtime: https://github.com/NousResearch/hermes-agent\n  Profile/history: ONBOARDER_AGENT_HOME (default: ~/.config/onboarder/agent).\n\n  onboarder agent ask . --task \"Explain the authentication flow\"\n  onboarder agent review . --pr 42 --task \"Find correctness and security issues\"\n  onboarder agent triage . --issue 12 --task \"Investigate and propose a fix\"\n  onboarder agent implement . --task \"Fix issue 12\" --issue 12 --allow-checks\n  onboarder agent pr . --task \"Fix issue 12 and open a draft PR\" --issue 12 --allow-checks --allow-github-writes\n";
+export declare const AGENT_OPTIONS: {
+    task: {
+        type: 'string';
+    };
+    pr: {
+        type: 'string';
+    };
+    issue: {
+        type: 'string';
+    };
+    'max-turns': {
+        type: 'string';
+    };
+    timeout: {
+        type: 'string';
+    };
+    resume: {
+        type: 'string';
+    };
+    'allow-checks': {
+        type: 'boolean';
+    };
+    'allow-github-writes': {
+        type: 'boolean';
+    };
+    'dry-run': {
+        type: 'boolean';
+    };
+    model: {
+        type: 'string';
+    };
+    provider: {
+        type: 'string';
+    };
+    json: {
+        type: 'boolean';
+    };
+    help: {
+        type: 'boolean';
+        short: string;
+    };
+    base: {
+        type: 'string';
+    };
+};
+export declare function agentDoctor(home?: string, env?: NodeJS.ProcessEnv): Promise<{
+    runtime: boolean;
+    compatible: boolean;
+    server: boolean;
+    profile: boolean;
+    githubToken: boolean;
+    home: string;
+    ready: boolean;
+    detail: string;
+    next: string;
+}>;
+export declare function fetchHermesSource(home?: string, signal?: AbortSignal): Promise<{
+    source: string;
+    revision: string;
+    directory: string;
+    license: string;
+    installed: boolean;
+}>;
+export declare function agentCommand(sub?: string, positionals?: string[], flags?: Record<string, any>, options?: {
+    root?: string;
+    signal?: AbortSignal;
+    out?: (text: string) => void;
+    err?: (text: string) => void;
+}): Promise<number>;
+export declare function explorerAgent(args: string[], root: string, signal: AbortSignal, out: (text: string) => void, err: (text: string) => void): Promise<string>;