@ipul-labs/forge 1.21.2 → 1.35.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ipul-labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -12,7 +12,7 @@ Built on: Claude Code CLI · GitLab / GitHub / Azure DevOps · Kubernetes
 
 Everything else fills in the gaps that matter for real teams:
 
-- **No per-token cost** — Claude runs via the `claude` CLI using your existing Claude subscription, not API credits. Heavy use doesn't trigger a bill.
+- **No per-token cost** — Claude runs via the `claude` CLI using your existing Claude subscription, not API credits. Heavy use doesn't trigger a bill. Hosted workspaces can instead save their own Anthropic API key (see [Claude billing](#claude-billing)).
 - **Multi-provider** — GitLab, GitHub, and Azure DevOps are all first-class. Switch providers with a single env var; all normalized data shapes stay the same.
 - **Self-hosted** — your code never leaves your infrastructure. The backend runs wherever you deploy it; AI calls go to Anthropic (or a local gateway via OpenClaw).
 - **Two-pass analysis keeps context focused** — Claude first identifies the 6 most relevant files, then reads only those when proposing the fix. This produces sharper diffs than dumping the whole repo into one prompt.
@@ -21,8 +21,8 @@ Everything else fills in the gaps that matter for real teams:
 
 ## How it works
 
-1. **Connect** — enter your Forge token to authenticate
-2. **Pick an issue** — Forge loads open issues from your project
+1. **Sign in** — with your Forge account or your company SSO
+2. **Pick an issue** — Forge loads open issues from your project. Create, edit, label (`type::` / `priority::` / `status::` / `area::`) and delete tickets right from Forge. Close and delete (in the issue's ⋯ menu) open a dialog that first shows what will be torn down (Forge branches deleted, review environments stopped) and names any open MR that blocks it; deleting also asks you to type the issue number. The preview comes from `GET /issues/:iid/footprint`
 3. **Analyze** — Claude reads the repo file tree, identifies relevant files, and proposes a targeted fix
 4. **Review** — inspect the diff file-by-file; refine with natural-language feedback if needed
 5. **Apply** — Forge creates a branch, commits all changes, and opens a merge/pull request
@@ -34,57 +34,54 @@ Everything else fills in the gaps that matter for real teams:
 
 ### Prerequisites
 
-- Node.js 20+
+- Node.js 22.13+
 - `claude` CLI installed and authenticated (`claude auth login`)
 - Credentials for your SCM provider (see [Configuration](#configuration))
 
 ### Install
 
+Forge is published on npm as [`@ipul-labs/forge`](https://www.npmjs.com/package/@ipul-labs/forge). The package includes the server, the built dashboard and the `forge` CLI.
+
 ```bash
-git clone https://gitlab.com/ipul-labs/forge.git
-cd forge
-npm install
+npm install -g @ipul-labs/forge
 ```
 
 ### Configure
 
+Pick a folder for this install's settings and run the setup there. It writes `.env` in that folder and your repos and code-host token to `~/.forge/config.json`:
+
 ```bash
-# Interactive setup — writes .env and ~/.forge/config.json
-npx forge init
+mkdir forge-home && cd forge-home
+forge init
 ```
 
-Or copy the example env and fill in the values manually:
+### Launch the dashboard
+
+From the same folder:
 
 ```bash
-cp .env.example .env
-# fill in FORGE_TOKEN plus your provider credentials
+forge start            # http://localhost:5001 (--port to change)
 ```
 
-### Launch the UI
+Open it and create the first admin account (see [First run](#first-run)). `forge doctor` checks the Claude CLI, your config and the build if anything looks off, and `forge update` installs the latest release.
 
-```bash
-npm run dev
-# opens http://localhost:5000 (frontend) with API on :5001
-```
+Prefer not to install globally? `npx @ipul-labs/forge init` and `npx @ipul-labs/forge start` do the same.
+
+### Working on Forge itself
 
-For production:
+From a checkout of the source:
 
 ```bash
-npm run build:app   # builds Vite SPA to dist/
-npm start           # NODE_ENV=production node server.js
+npm install
+npm run dev            # http://localhost:5000 (frontend) with the API on :5001
+npm run build && npm start   # production build, served on :5001
 ```
 
-### CLI usage
+`npm run test:package` packs the repo exactly as npm would, installs the tarball into an empty folder, and runs the end-to-end checks against that install.
 
-The `forge` CLI drives the same orchestrator from the terminal. Install globally or use `npx`:
-
-```bash
-# Global install (adds `forge` to PATH)
-npm install -g @ipul-labs/forge
+### CLI usage
 
-# Or run via npx from the repo
-npx forge <command>
-```
+The `forge` CLI drives the same orchestrator from the terminal. After the global install above it is on your PATH; otherwise prefix commands with `npx @ipul-labs/forge`.
 
 #### Interactive mode
 
@@ -130,8 +127,7 @@ forge merge                    # Merge the MR
 forge resolution-check         # Verify merged MR closes the issue
 forge close                    # Close the issue
 forge use group/other-repo     # Switch active repo
-forge update                   # Pull latest + reinstall dependencies
-forge stats                    # View telemetry — success rates, timing, failure patterns
+forge update                   # Install the latest release (a source checkout pulls instead)
 forge improve                  # Evaluate patterns and suggest improvements
 forge improve --create         # Create improvement issues in the repo
 ```
@@ -144,7 +140,7 @@ forge improve --create         # Create improvement issues in the repo
 --secondary <repo>       Additional repo (repeatable)
 --all-repos              Include every configured repo
 --model <id>             Claude model override
---agent <name>           Agent backend: claude | openclaw
+--agent <name>           Agent backend: claude
 --prompt <text>          Extra user prompt
 --json                   JSON output
 --quiet                  Suppress progress
@@ -158,9 +154,12 @@ forge improve --create         # Create improvement issues in the repo
 forge doctor             # Check prerequisites (node, claude CLI, env vars)
 forge session list       # List cached sessions
 forge session clean      # Remove stale session data
+forge reset-password <email>  # Locked out? Set a new password on the Forge host
 ```
 
-See [`docs/cli.md`](./docs/cli.md) for the full command reference and [`docs/cli-ship-workflow.md`](./docs/cli-ship-workflow.md) for the workflow design.
+`reset-password` writes straight to the Forge database (`FORGE_DB_PATH`, default `~/.forge/forge.db`), so it works without signing in and only for someone with shell access to the host. It asks for the new password twice without echoing it (or reads one line from piped stdin), signs the account out everywhere, and records `user.password_reset` in the audit log. SSO accounts are refused; their passwords live with the identity provider.
+
+`forge help` lists every command and its options.
 
 ---
 
@@ -170,16 +169,35 @@ See [`docs/cli.md`](./docs/cli.md) for the full command reference and [`docs/cli
 
 | Variable | Required | Description |
 |---|---|---|
-| `FORGE_TOKEN` | Yes | Dashboard password — also auto-fills the UI login form |
+| `FORGE_TOKEN` | — | Admin credential for automation; also accepted as the remote setup code. Never sent to the browser |
 | `FORGE_REPOS` | Yes | Comma-separated repo list; first entry is the primary project |
 | `SCM_PROVIDER` | — | `gitlab` (default) · `github` · `azuredevops` |
-| `ANTHROPIC_API_KEY` | — | Enables live model list from Anthropic; falls back to hardcoded list |
+| `ANTHROPIC_API_KEY` | — | Enables live model list from Anthropic; falls back to hardcoded list. Never used to run Claude |
 | `FORGE_MODEL` | — | Override default model (default: `claude-sonnet-4-6`) |
-| `K8S_CLUSTER_TOKEN` | — | K8s service account token for rollout monitoring |
-| `K8S_CLUSTER_SERVER` | — | K8s API server URL |
+| `FORGE_AGENT_MODE` | — | `structured` (default) · `agentic` — how Claude proposes changes (see [Agent modes](#agent-modes)) |
 | `PORT` | — | HTTP server port (default: `5001`) |
-| `OPENCLAW_GATEWAY_URL` | — | Enables OpenClaw agent backend; point at your local Gateway |
-| `OPENCLAW_TOKEN` | — | Bearer token for OpenClaw Gateway auth |
+
+### Identity and storage
+
+| Variable | Required | Description |
+|---|---|---|
+| `FORGE_DB_PATH` | — | SQLite database for members, sessions, API tokens and the audit log (default `~/.forge/forge.db`) |
+| `FORGE_ENCRYPTION_KEY` | — | Base64 32-byte key used to encrypt SCM tokens at rest. Without it Forge generates `~/.forge/master.key` (`FORGE_KEY_PATH`) |
+| `FORGE_OIDC_ISSUER` | — | OIDC issuer URL (Okta, Entra ID, Google Workspace, GitLab, …). Enables "Continue with SSO" |
+| `FORGE_OIDC_CLIENT_ID` / `FORGE_OIDC_CLIENT_SECRET` | — | OIDC client credentials |
+| `FORGE_PUBLIC_URL` | — | External URL; the OIDC redirect is `${FORGE_PUBLIC_URL}/api/forge/auth/oidc/callback` unless `FORGE_OIDC_REDIRECT_URI` is set |
+| `FORGE_OIDC_NAME` | — | Label on the sign-in button (default `SSO`) |
+| `FORGE_OIDC_ALLOWED_DOMAINS` | — | Comma-separated email domains allowed to sign in with SSO |
+| `FORGE_OIDC_DEFAULT_ROLE` | — | Role given to new SSO members (default `viewer`) |
+| `FORGE_TRUST_PROXY` | — | Express `trust proxy` setting when behind a load balancer |
+| `FORGE_COOKIE_SECURE` | — | Override Secure cookies (on by default in production) |
+| `FORGE_DISABLE_SERVICE_TOKEN` | — | `1` stops `FORGE_TOKEN` working as an API credential once setup is done |
+
+### Claude billing
+
+By default the `claude` CLI runs on the Claude Code subscription it is logged in with, and Forge strips `ANTHROPIC_API_KEY` from its environment so an env key can't quietly switch it to API credits.
+
+An admin can save a workspace **Anthropic API key** in Settings → Connections. Claude then runs on that account's API credits instead. This is the mode for a hosted Forge serving other teams, since a personal subscription is only for its owner's own use. The key is encrypted at rest like SCM tokens, shown back only as a hint, and clearing it returns Claude to the subscription.
 
 ### Provider credentials
 
@@ -215,7 +233,6 @@ SCM tokens can be set here **or** in the Forge Settings UI (Settings → Connect
 | Variable | Replaced by |
 |---|---|
 | `FORGE_GITLAB_PROJECT` | First entry in `FORGE_REPOS` |
-| `VITE_FORGE_TOKEN` | Auto-derived from `FORGE_TOKEN` |
 | `FORGE_REFINE_REPO_ACCESS` | Settings UI toggle (Settings → Defaults) |
 
 See `.env.example` for a full annotated list.
@@ -250,33 +267,14 @@ FORGE_REPOS=gitlab:ipul/web-app,github:my-org/mobile
 | Multi-file commits | Yes | Yes (Git Data API) | Yes (Pushes API) |
 | Merge / Pull Requests | Yes | Yes | Yes |
 | CI pipelines | Yes (GitLab CI) | Yes (GitHub Actions) | Yes (Azure Pipelines) |
+| Pipeline history page | Yes | — | — |
 | Job log traces | Yes | Yes | Yes |
 | Server-side rebase | Yes | — | — |
+| Ticket labels | Yes | Yes | Yes (Tags) |
+| Delete tickets | Yes (project Owner) | — (close instead) | Yes (recycle bin) |
+| Review env link on MRs | Yes (environment deployed by the MR pipeline) | — | — |
 
----
-
-## Self-improvement
-
-Forge monitors its own performance and proposes fixes autonomously. The loop:
-
-1. **Telemetry** — every operation records success/fail, duration, tokens, and cost to `~/.forge/telemetry/`
-2. **Pattern detection** — recurring failures are grouped and classified (timeout-tuning, provider-bug, prompt-quality, validation-gap, error-handling, ux-improvement)
-3. **Auto-evaluation** — runs automatically after every 25 operations (4-hour cooldown). High-severity patterns trigger issue creation.
-4. **Issue creation** — files issues in the configured repo with diagnosis, evidence, and suggested fixes. Tagged `[self-improve]` with category labels.
-5. **Human review** — Forge never auto-merges its own changes. All improvements go through normal MR review.
-6. **Resolution** — when a self-improve issue is closed, matching telemetry failure patterns are marked as resolved. They stop appearing in `forge stats` and won't trigger duplicate diagnoses. Resolution is tied to code state, not time — patterns only clear when the fix ships.
-
-```bash
-forge stats                    # View telemetry data
-forge improve                  # Run evaluation manually
-forge improve --create         # Create issues for actionable patterns
-forge improve --ship           # Create issues + analyze + propose fix + open MR
-forge improve --json           # Pipe-friendly output
-```
-
-The `--ship` flag runs the full loop: detect pattern → create issue → analyze → propose fix → open MR. All in one command. The MR goes through normal CI — you review and merge or reject.
-
-UX insights are also derived from telemetry: slow operations (>2 min avg), high token usage (>50k avg), and frequent cancellations surface as improvement suggestions.
+On GitLab, the MR tab shows a **Review env ↗** link when the MR's pipeline has deployed a live environment with an external URL (e.g. a `review/mr-<iid>` job with `environment:url`). No config needed; MRs without one show nothing.
 
 ---
 
@@ -284,8 +282,13 @@ UX insights are also derived from telemetry: slow operations (>2 min avg), high
 
 Forge is designed for self-hosted deployment on trusted infrastructure. Security measures in place:
 
-- **Timing-safe auth** — token comparison uses `crypto.timingSafeEqual` to prevent timing attacks
-- **Rate limiting** — API endpoints are rate-limited (60 req/min per IP) to prevent brute-force
+- **Member accounts** — each person signs in with a password (scrypt) or SSO (OIDC with PKCE). Sessions are httpOnly, SameSite cookies stored server-side as hashes, with a 12-hour idle and 7-day absolute limit. No credential ever reaches browser JavaScript or the client bundle
+- **Roles** — viewer, operator, approver and admin, enforced on every API route. Merging needs approver; connections, repos and members need admin
+- **Audit log** — every sign-in and every change is recorded with who, what, where and the outcome. It is append-only and visible to admins under Audit log
+- **Encryption at rest** — SCM tokens in `~/.forge/config.json` are sealed with AES-256-GCM
+- **CSRF protection** — cookie-authenticated writes require a custom request header
+- **Brute-force protection** — accounts lock for 15 minutes after 5 failed sign-ins, and sign-in endpoints are rate-limited per IP. API calls are rate-limited per member
+- **API tokens** — personal tokens for the CLI and automation, shown once, stored hashed and revocable
 - **Security headers** — Helmet middleware sets X-Frame-Options, HSTS, X-Content-Type-Options, and CSP (production)
 - **Request size limits** — JSON body capped at 1MB to prevent memory exhaustion
 - **Secret redaction** — error logs and API responses scrub tokens (`glpat-*`, `ghp_*`, `oauth2:*@`) before output
@@ -295,22 +298,41 @@ Forge is designed for self-hosted deployment on trusted infrastructure. Security
 - **No shell injection** — all subprocess calls use `spawn()` with argument arrays, never shell strings
 - **Atomic config writes** — config updates use temp file + rename to prevent corruption
 
-`FORGE_TOKEN` is a standalone dashboard password — never reuse an SCM token for this value.
+`FORGE_TOKEN`, when set, is an admin credential for automation. Use a long random value, never reuse an SCM token, and set `FORGE_DISABLE_SERVICE_TOKEN=1` once your team uses personal API tokens.
+
+### First run
+
+Open Forge and create the first admin account. On the server machine itself (`localhost`) that is all it takes. From anywhere else the form asks for a setup code, which Forge prints to its log on first start (or your `FORGE_TOKEN`, if set), so nobody can claim a fresh install that is reachable on the network. Add the rest of your team under **Members**, or turn on SSO with the `FORGE_OIDC_*` variables.
+
+The `forge` CLI authenticates with a personal API token: create one under **Settings → API tokens** and export it as `FORGE_API_TOKEN`.
 
 ---
 
 ## Production deployment
 
+On a server, install from npm and run `forge start` as a service (systemd, pm2 or similar) from the folder holding your `.env`. Put it behind your HTTPS reverse proxy and set `FORGE_PUBLIC_URL` to the address people use.
+
+From a source checkout:
+
 ```bash
-npm run build:app      # builds Vite SPA to dist/
+npm run build          # builds the SPA to dist/
 NODE_ENV=production tsx server.ts
 ```
 
-Or with Docker:
+Or with Docker, from a checkout:
 
 ```bash
 docker build -t forge .
-docker run -p 5001:5001 --env-file .env forge
+docker run -p 5001:5001 --env-file .env -v forge-data:/data forge
+```
+
+### Kubernetes
+
+`manifests/forge/` holds an example Deployment, Service, ConfigMap and Secret template. Build and push the Docker image to your own registry, set `image` in `deployment.yaml`, create the secret, then:
+
+```bash
+kubectl create namespace forge
+kubectl apply -n forge -f manifests/forge/
 ```
 
 ---
@@ -339,9 +361,7 @@ server/
     core/
       ForgeAgent.ts     # Orchestrates the full pipeline (analyze -> apply -> refine)
       claudeClient.ts   # Shells out to the claude CLI for structured output
-      openclawClient.ts # OpenClaw Gateway HTTP client
-      agentClient.ts    # Dispatcher: routes to claudeClient or openclawClient
-      k8s.ts            # Kubernetes client for rollout monitoring
+      agentClient.ts    # Thin wrapper over claudeClient
       jobs.ts           # Job store with SSE event buffering + replay
       providers/
         base.ts         # Abstract ScmProvider — normalized shapes + interface
@@ -353,16 +373,67 @@ server/
 src/
   views/Forge/
     ForgeDashboard.tsx      # Root UI component with tabbed issue/MR views
-    api.ts                  # Token management + fetch helper
+    api.ts                  # Session-aware fetch helper (cookie + CSRF header)
     types.ts                # Shared TypeScript types
     utils.ts                # SSE helper + state utilities
-    components/             # Analysis progress, pipeline status, diff viewer
+    ui.ts                   # Shared responsive class tokens (touch-sized actions)
+    components/             # Analysis progress, pipeline status, diff viewer, Sheet, Switch
+    shell/                  # App chrome: sidebar (drawer on phones), top bar, command palette, phone tab bar
+      useNav.ts             # Single nav definition shared by sidebar, tab bar and command palette
     hooks/
       useForgeDashboard.ts  # All state, phase transitions, and API calls
       useForgeEvents.ts     # SSE event bus subscription
 ```
 
-### Two-pass analysis
+### Mobile layout
+
+Below Tailwind's `md` breakpoint (768px) the dashboard adds iOS-style touches on top of the responsive shell: a bottom tab bar (Issues · Merge requests · Pipelines · Settings) on list pages, a New task button in the top bar, New Task as a bottom sheet, iOS switches, full-width 50pt primary actions, and 16px form fields so Safari doesn't zoom. The sidebar (repo picker, usage, theme, admin pages, sign-out) opens as a drawer from the top bar. It respects safe-area insets and uses `100dvh`, so it works as a home-screen web app on iPhone. Desktop layout is unchanged.
+
+### Install as an app (PWA)
+
+Forge ships a web app manifest (`public/manifest.webmanifest`) and icons, so it can be installed. On iPhone open it in Safari → Share → **Add to Home Screen**; on Android/Chrome use **Install app**. It opens standalone at `/issues`. The icon source is `public/icon.svg`; regenerate the PNGs after changing it:
+
+```bash
+for s in 180 192 512; do magick -background none -density 384 public/icon.svg -resize ${s}x${s} -strip PNG32:public/icon-$s.png; done
+mv public/icon-180.png public/apple-touch-icon.png
+```
+
+If the app bundle fails to load or throws before React mounts, `public/boot-check.js` reloads once (a stale bundle after a deploy) and then shows the error with the browser's user agent and a Reload button instead of a blank screen. In production a missing file under `/assets/` returns 404 rather than `index.html`, so a stale bundle fails visibly.
+
+### Agent modes
+
+Forge can drive Claude in two ways, set by `FORGE_AGENT_MODE` (or the Settings default, or a per-request `agentMode`):
+
+- **`structured`** (default) — the two-pass JSON pipeline below. Deterministic and schema-validated: Claude runs single-turn with tools disabled and returns complete file contents that Forge overlays onto a clone.
+- **`agentic`** — Claude runs as a full Claude Code agent inside a checkout of the repo: real tools (Read/Edit/Write/Bash…), the project's own `CLAUDE.md`, and a multi-turn loop. Forge captures the resulting `git diff` instead of parsing JSON, then feeds those changes into the same apply/validate/MR pipeline. The capture never includes symlinks or dependency folders (`node_modules`, `bower_components`, `jspm_packages`, `.venv`, `__pycache__`), whatever the repo's `.gitignore` says; anything left out is noted in the run log. Higher fidelity, less determinism. Requires the `claude` backend, a single repo, and a GitLab primary — otherwise Forge logs why and falls back to structured. Pick the mode under **Settings → Defaults → Agent mode**.
+
+  Refine follows the mode too. In agentic mode a follow-up ("open it in Playwright and check it", "rename the prop") runs as the same full agent in the issue's worktree with the current proposal already applied, so it can run tests and browsers, gather evidence and edit. If it changes nothing and gathers no evidence, its reply comes back as an answer and the proposal is left as it was. In structured mode, refine only gets read-only repo access (Read/Glob/Grep), so it can't run anything. CI-fix refines always use the structured fix.
+
+### Rules and evidence
+
+**Settings → Defaults → Prompt rules** is free text added to every analysis and refine prompt as "Custom rules — always follow these", in both modes. In agentic mode the target repo's `CLAUDE.md` applies as well, so repo conventions belong there and Forge-wide instructions belong in the rules.
+
+In agentic mode a rule can also ask for proof, e.g. *"Run the e2e tests and screenshot every page you changed, at desktop and phone width."* Forge doesn't capture anything itself: the agent installs and runs what it needs (Playwright and its browsers included) and leaves the results in `.forge-evidence/` at the checkout root:
+
+- `.forge-evidence/EVIDENCE.md` — what it ran and what it saw; images are linked by file name (`![home](home.png)`)
+- PNG/JPEG/GIF/WebP screenshots next to it (nested folders are fine; up to 10 images, 10 MB each)
+
+After the run Forge uploads the images to the GitLab project, points the write-up's links at the uploads (appending any image it didn't mention), and puts the result in the MR's **🧪 Testing** section. The folder is cleared before each run and listed in the clone's `.git/info/exclude`, so it is never committed. A failed upload is logged in the activity feed and doesn't fail the analysis. The agent's run is bounded by `cliTimeout` (10 minutes by default), so a full browser install plus a long suite may need more.
+
+### Workspaces
+
+Every local checkout Forge works in lives under `~/.forge/cache` (or `FORGE_VALIDATE_CACHE`):
+
+```
+repos/<repo>/                  shallow base clone, one per repo
+worktrees/<repo>/issue-<iid>/  git worktree per issue, on its forge/issue-… branch
+```
+
+Agentic runs, refine (with repo access) and validation each lease the issue's worktree, reset it to the remote HEAD, and release it when done. Different issues never share a tree, and git work on one repo (fetch, worktree add/remove) is serialised. Ignored files such as `node_modules` survive between runs of the same issue.
+
+**Settings → Workspaces** (admins) lists every base clone and worktree with its size, last use and whether a running job holds it, plus anything Forge doesn't own any more: clones from the old one-clone-per-repo layout ("Old-layout clone") and worktree folders git no longer knows about ("Stray folder"). You can delete one, or **Purge idle** to remove everything not in use; tick *Include base clones* to drop base clones that have no worktrees left too. A deleted workspace is simply re-created by the next job that needs it. The same actions are available as `GET /workspaces`, `DELETE /workspaces?id=<id>` and `POST /workspaces/purge` (`{"includeBases": true}`); a workspace in use answers 409.
+
+### Two-pass analysis (structured mode)
 
 **Pass 1** — `identifyRelevantFiles`: Claude reads the issue + file tree, returns the max-6 most relevant paths.
 
@@ -388,11 +459,13 @@ All three SCM providers implement `ScmProvider` from `providers/base.ts`. The co
 The npm package ships compiled JavaScript with TypeScript declarations — no `tsx` or TypeScript runtime needed by consumers.
 
 ```ts
-import forgeRouter from "@ipul-labs/forge";             // Express router
+import { createApi } from "@ipul-labs/forge/app";       // Express app with auth + API
 import { ForgeAgent } from "@ipul-labs/forge/agent";    // Core pipeline class
 import { createProvider } from "@ipul-labs/forge/providers"; // SCM factory
 ```
 
+The bare router (`@ipul-labs/forge`) expects the auth stack in front of it and rejects requests without a signed-in principal. Mount `createApi({ db, env: process.env, isProd })` instead, with `db` from `openDatabase`.
+
 ```ts
 const agent = new ForgeAgent({ project: "group/repo" });
 const result = await agent.analyzeIssue(42, (event) => console.log(event));
@@ -411,6 +484,16 @@ npm run typecheck        # check both frontend + server configs
 
 ---
 
+## Contributing
+
+The source repository is private for now. Send bug reports, ideas and security problems to support@ipullabs.com; please report security problems privately rather than in public.
+
+## Support
+
+Questions or problems with Forge: support@ipullabs.com
+
+---
+
 ## License
 
-MIT
+MIT. Forge is free to use, change and share, for personal or commercial work. The full license text is in the `LICENSE` file that ships with the package.