poolanithinreddy · poolanithinreddy · Aug 11, 2026 · Jun 8, 2026 · Jun 8, 2026 · Jun 8, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -25,4 +25,5 @@ jobs:
       - run: npm run build
       - run: npm test
       - run: npm run check:file-size
+      - run: npm run check:audit
       - run: npm pack --dry-run
diff --git a/.gitignore b/.gitignore
@@ -5,10 +5,11 @@ coverage/
 *.log
 logs/
 tmp/
-/.opencode-agent/
-
 # Local runtime/dogfood state and other-tool configs — not part of the CLI repo.
 /.apeironcode-agent/
+# Repair-loop checkpoints (Phase 20B) and UI-smoke artifacts (Phase 20D).
+.apeironcode/checkpoints/
+.apeironcode/ui-smoke/
 /.agents/
 /.codex/
 /.claude/

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,8 +10,8 @@
 
 ### Changed
 
-- `APEIRONCODE_TEST_OFFLINE` is now the preferred sandbox offline flag; `OPENCODE_TEST_OFFLINE` is kept as a deprecated legacy alias.
-- Documentation now uses the `APEIRONCODE_AUTOMATION*` environment variables as the primary names (the `OPENCODE_AUTOMATION*` aliases remain deprecated).
+- `APEIRONCODE_TEST_OFFLINE` disables sandbox backend probing in offline test runs.
+- Documentation and automation use only the `APEIRONCODE_*` environment namespace.
 
 ### Added
 
@@ -150,7 +150,7 @@
 - `apeironcode lsp symbols` and `/lsp symbols` try live `documentSymbol` first and preserve fallback behavior when live LSP is missing or fails
 - `apeironcode lsp diagnostics`, `apeironcode lsp definition`, and `apeironcode lsp references` now report live-vs-fallback results instead of placeholder or ambiguous output
 - the shared agent project context now enriches relevant workflows with capped diagnostics and reports diagnostics source, files checked, counts, and fallback reasons in final summaries
-- agent loop now supports multi-tool turns, `<opencode_tool_call>`, and malformed tool-call retry prompts
+- agent loop now supports multi-tool turns, `<apeironcode_tool_call>`, and malformed tool-call retry prompts
 - one-shot CLI preamble, final execution summary, session metadata, and TUI status now share the same effective-mode resolution
 - slash workflow help now includes `/commands`, usage examples, and better missing-argument guidance
 - approval prompts, provider diagnostics, slash output, and error panels now safely stringify unexpected structured values

diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 ApeironCode Agent contributors (formerly OpenCode Agent)
+Copyright (c) 2026 ApeironCode contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ 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.
+SOFTWARE.
diff --git a/README.md b/README.md
@@ -30,12 +30,85 @@ Verify the installation:
 
 ```bash
 apeironcode --help
-apeironcode setup --provider mock
+apeironcode demo
 apeironcode doctor
 ```
 
-Mock mode is deterministic and needs no API key. For real work, configure
-[Ollama or a cloud provider](./docs/providers.md).
+## Try the demo (no API key)
+
+`apeironcode demo` runs deterministic, local examples — no API key, model, or
+Ollama required:
+
+```bash
+apeironcode demo todo-app     # scaffold a working static todo app
+apeironcode demo fix-test     # reproduce a failing test, then fix it to green
+apeironcode demo improve-ui   # turn a plain page into a premium one
+apeironcode demo review       # deterministic review of a sample diff
+```
+
+Demo mode uses deterministic local examples, not a model. For real projects,
+configure [Ollama or a cloud provider](./docs/providers.md). The `mock`
+provider is a deterministic test/demo stub, **not** a real coding model.
+
+## Four workflows
+
+ApeironCode is a local-first coding agent centered on four workflows, all with
+approval-gated writes and commands:
+
+```bash
+apeironcode fix                    # detect failures, propose fixes, rerun checks
+apeironcode new "a todo app"       # create a new app from a template
+apeironcode build "a CRM dashboard"# build also creates apps from templates
+apeironcode improve "premium UI"   # improve UI or code quality
+apeironcode review                 # review the current changes
+```
+
+## Build an app
+
+`apeironcode new` (and `apeironcode build`) create a small app from a
+**deterministic template** — no API key or model needed:
+
+```bash
+apeironcode new "premium todo app"
+apeironcode new "CRM dashboard" --stack dashboard
+apeironcode new "landing page for an AI startup" --style premium-saas
+apeironcode build "a React task app" --stack vite --dir my-app
+```
+
+It picks a template, shows an approval bundle, writes real files, and validates
+them (linked assets, `node --check`, a design checklist). Static apps
+(todo/landing/dashboard) are the most reliable and need no install; Vite + React
+is alpha and needs a manual `npm install`. Auth/database/billing requests become
+**mock/local UI**, not real backends — the report is honest about scope. A
+non-empty directory is never overwritten silently. See
+[docs/build-apps.md](./docs/build-apps.md).
+
+Verify a generated app actually renders in a browser:
+
+```bash
+apeironcode test-ui ./my-app          # page load, missing assets, console errors, screenshot
+apeironcode new "todo app" --ui-smoke # run the smoke during creation
+```
+
+`test-ui` uses Playwright/Chromium when available; without a browser it reports
+*skipped*, never a fake pass (`npx playwright install chromium` to enable). It is
+not a full QA replacement. See [docs/ui-smoke.md](./docs/ui-smoke.md).
+
+`apeironcode fix` detects your project's check commands (typecheck/lint/test/
+build), runs them, proposes an **approval-gated** minimal patch, applies it, and
+reruns the checks. Use `--dry-run` to preview, `--safe` to restrict the edit
+scope, and `--until-green` to loop. See [docs/fix-code.md](./docs/fix-code.md).
+It is alpha — you review and approve every change, and repair quality depends on
+your configured provider.
+
+Workflows render a compact progress board (plan, files, command log, artifacts)
+with one approval bundle before any write or command. High-risk commands
+(`rm -rf`, `sudo`, `curl | sh`, `npm publish`, `git push --force`) are never
+auto-approved. `apeironcode fix` checkpoints before applying, so you can
+`apeironcode rollback --last`. See [docs/terminal-ux.md](./docs/terminal-ux.md).
+
+`apeironcode --help` is beginner-focused. Run `apeironcode help developer` or
+`apeironcode help advanced` for the full command set.
 
 ## See It Work
 
@@ -116,7 +189,7 @@ See the [complete action example](./examples/github-action-pr-review/).
 - Terminal-native interactive chat built with Commander.js, Ink, and React.
 - One-shot execution for direct prompts from the shell.
 - `apeironcode doctor` diagnostics and `apeironcode provider test` smoke checks.
-- Optional Project Brain: `apeironcode brain plan` previews a user-approved `.apeironcode/` workspace memory for long app builds, with large-app orchestration, PLAN/TASKS diff-merge, a persistent sync-preview store, token-efficient context planning, and agent routing. All writes require explicit `--yes` — no silent creation. Runtime brain intelligence adds deterministic intent classification (<1ms) that selects relevant brain context per prompt, surfaced via the `brain.runtime`/`brain.explain` CLI. (A VS Code companion exists in development but is not part of this CLI alpha.)
+- Optional Project Brain: `apeironcode brain plan` previews a user-approved `.apeironcode/` workspace memory for long app builds, with large-app orchestration, PLAN/TASKS diff-merge, a persistent sync-preview store, token-efficient context planning, and agent routing. All writes require explicit `--yes` — no silent creation. Runtime brain intelligence adds deterministic intent classification (<1ms) that selects relevant brain context per prompt, surfaced via the `brain.runtime`/`brain.explain` CLI.
 - First-run setup with `apeironcode setup`, no-key mock-provider trial mode, `/setup`, and setup status/reset commands.
 - TUI product-home flow with command echo, compact dashboard sections, `/commands beginner`, natural aliases such as `/show memory`, and temp-HOME smoke helpers via `npm run demo:tui`.
 - Provider readiness UX with `apeironcode provider list`, `apeironcode provider setup`, `apeironcode provider fallback`, `apeironcode provider doctor`, `apeironcode model list`, and `apeironcode model recommend`.
@@ -155,7 +228,8 @@ See the [complete action example](./examples/github-action-pr-review/).
 - Lifecycle hooks wired into sessions, planning, tools, edits, commands, commits, memory suggestions, and skill runs, with disabled-by-default shell execution and explicit approval requirement.
 - Token-efficient repo brain modules for file summaries, dependency edges, context packing, prompt-context injection, and budget reporting.
 - Typed code quality workflow recipes for feature implementation, test fixes, debugging, review, refactor, tests, dependency upgrades, security/performance audits, docs, and release prep, with dry-run, report storage, and runtime execution through the agent loop.
-- Honest sandbox status detection with `apeironcode sandbox status`; OS-level sandboxed command execution is not implemented.
+- Central command policy with `apeironcode sandbox status`: blocked commands are refused before execution, Docker is used for suitable commands when available/configured, and native fallback is clearly reported as approval-gated but not OS-isolated.
+- In native fallback, command execution is not process-isolated by default.
 - Mock-only local eval commands with `apeironcode eval list`, `apeironcode eval run smoke`, and `apeironcode eval report`.
 
 ## Provider Matrix
@@ -177,13 +251,13 @@ ApeironCode uses a bring-your-own-key model for cloud providers. API keys are re
 
 - Read-only operations are low risk by default.
 - File edits and writes always show a diff before approval.
-- Shell commands, tests, and commits always require approval unless you explicitly pass `--dangerously-skip-approvals`.
+- Shell commands are classified before execution. `--yes` and `--dangerously-skip-approvals` do not approve high-risk or blocked commands.
 - Web access is ask-first by default because outbound requests must match an explicit `Network(...)` allow rule or be approved interactively.
 - `web_fetch` only supports `http:` and `https:` URLs and blocks `localhost` and private IP ranges unless `web.allowPrivateHosts=true` is set for trusted local testing.
 - `web_search` and `web_research` redact obvious secret-like query fragments before building outbound requests.
 - Sensitive files such as `.env`, SSH keys, and secret stores require explicit approval.
 - Commands like `sudo`, `curl | sh`, `wget | sh`, and system path permission changes are blocked.
-- High-risk commands such as `rm -rf`, destructive git resets, and `npm publish` require extra confirmation.
+- High-risk commands require explicit manual confirmation. Blocked commands such as `npm publish`, `sudo`, pipe-to-shell installers, broad workspace escapes, and forced/mirrored pushes do not run by default.
 
 ## Slash Commands
 
@@ -509,6 +583,8 @@ npm run bench:agent
 - `docs/memory.md` covers project memory, global memory, and session learning.
 - `docs/history.md` covers `history`, `search`, and stored edit/task/session data.
 - `docs/mcp.md` covers the experimental MCP runtime and current limitations.
+- `docs/testing.md` explains mock/scripted CI coverage and real-provider limits.
+- `docs/sandbox.md` explains why approval gating is not an OS security boundary.
 
 ## Demo
 
@@ -521,7 +597,7 @@ build / modify / error-fix flows.
 - Next: richer history and memory dashboards inside the TUI.
 - Next: additional web search providers and richer result extraction.
 - Next: broader MCP transport support beyond the current experimental stdio runtime.
-- Later: a polished VS Code companion (in development, not part of this CLI alpha).
+- Later: optional IDE integrations. None are included in this CLI alpha.
 
 ## Known limitations
 
@@ -536,6 +612,8 @@ build / modify / error-fix flows.
 - The real TTY interaction harness is still limited.
 - No full autonomy is claimed — file writes and shell commands are
   approval-gated.
+- Default CI uses fixtures, mocked network responses, and the mock provider.
+  Real-provider/real-LLM checks require user credentials and are not run by CI.
 
 ## Attribution
 

diff --git a/action.yml b/action.yml
@@ -30,9 +30,6 @@ inputs:
   apeironcode_config_path:
     description: 'Path to an ApeironCode config file (optional).'
     required: false
-  opencode_config_path:
-    description: 'Legacy alias of apeironcode_config_path. Path to an ApeironCode config file (optional).'
-    required: false
 runs:
   using: 'composite'
   steps:
@@ -50,7 +47,6 @@ runs:
         INPUT_MAX_ITERATIONS: ${{ inputs.max_iterations }}
         INPUT_RUN_TESTS: ${{ inputs.run_tests }}
         INPUT_APEIRONCODE_CONFIG_PATH: ${{ inputs.apeironcode_config_path }}
-        INPUT_OPENCODE_CONFIG_PATH: ${{ inputs.opencode_config_path }}
         GITHUB_TOKEN: ${{ github.token }}
       run: '"$GITHUB_ACTION_PATH/node_modules/.bin/tsx" "$GITHUB_ACTION_PATH/src/githubAction/main.ts"'
 branding:

diff --git a/docs/agents.md b/docs/agents.md
@@ -41,8 +41,6 @@ apeironcode brain route "review the auth module for security issues"
 # → selects: security-reviewer, reviewer
 ```
 
-In VS Code, use **ApeironCode: Route Prompt to Brain** or the **Route Prompt** button in the Project Brain panel.
-
 ## Commands
 
 ```bash

diff --git a/docs/bridge.md b/docs/bridge.md
@@ -122,24 +122,14 @@ Protected paths (`.env`, `.git/`, private keys) are flagged as `risky: true`.
 
 Connect via: `ws://127.0.0.1:<port>`
 
-## VS Code Extension (Phase 16F)
+## Future IDE Integrations
 
-The extension at `extensions/vscode/` provides:
-
-- Sidebar chat panel streaming bridge events
-- Bridge connection management (start/stop)
-- Permission approve/deny UI
-- Diff preview with risky-path warnings
-- Task and worktree status view
-- Context view (files, token budget, provider)
-- Selected file/range context capture
-
-See `docs/vscode-extension.md` for setup.
+The public alpha does not include an IDE extension. The bridge is an
+experimental local API that may support future VS Code, JetBrains, desktop, or
+web integrations.
 
 ## Known Limitations (Phase 16F)
 
 - No remote/cloud bridge (local-only is intentional and enforced).
 - `diff.apply_requested` / `diff.apply_result` not connected to tool path (auto-apply disabled in MVP).
-- Prompt submission from VS Code webview pending bridge command routing.
-- No JetBrains or other IDE extension yet.
-- No VS Code Marketplace release yet.
+- No public IDE extension or Marketplace release.
diff --git a/docs/build-apps.md b/docs/build-apps.md
@@ -0,0 +1,93 @@
+# Building apps with `apeironcode new`
+
+ApeironCode builds small apps from **deterministic templates** — no API key or
+model is required for template generation. AI customization (via a configured
+provider) is an optional layer on top.
+
+```bash
+apeironcode new "premium todo app"
+apeironcode new "CRM dashboard" --stack dashboard
+apeironcode new "landing page for an AI startup" --style premium-saas
+apeironcode new "a React task app" --stack vite --dir my-app
+apeironcode build "create a premium todo app"     # build also creates apps
+```
+
+`apeironcode new` and `apeironcode build` run the same app-builder engine:
+parse the idea → pick a template → show an approval bundle **with a diff preview
+of the files to be created** → create real files → run validation → print a
+**Plan** checklist and completion panel with how to open the app.
+
+## Supported templates
+
+| Stack | Template | Notes |
+| --- | --- | --- |
+| `static` | static todo | HTML/CSS/JS. **Most reliable today** — no install, always works. |
+| `static` | static landing | Premium landing page with a mock waitlist. |
+| `dashboard` | static dashboard | Responsive, frontend-only dashboard with local sample data. |
+| `vite` | Vite + React (TypeScript) | Alpha. Requires `npm install` to run; the CLI does not auto-install. |
+
+Next.js is not available yet; a Next.js request downgrades to Vite + React and
+says so honestly.
+
+## What's a mock, and what's real
+
+This phase builds **frontend prototypes**. To stay honest:
+
+- "login", "auth", "sign in" → a **mock login** UI only (no real backend).
+- "CRM", "customers", "orders" → **local sample data** rendered in the browser.
+- "billing", "payments" → a **mock** UI only.
+
+ApeironCode does not create real authentication, databases, or billing in this
+phase, and the final report says so.
+
+## Validation
+
+After creating files, ApeironCode validates the app:
+
+- **Static apps**: files exist, the HTML's linked CSS/JS exist, `node --check`
+  passes on the JS, and a design checklist (title, viewport, labels, responsive
+  rules, no obvious overflow) passes. No network required.
+- **Vite apps**: `npm run build` / `npm run typecheck` are detected. The CLI
+  does **not** auto-install or run them; run `npm install && npm run dev`
+  yourself. They are reported as *skipped*, never as a fake pass.
+
+If a static app fails validation, the report shows exactly which check failed —
+it never claims a broken app passed.
+
+## Browser UI smoke
+
+After creating a static app you can open it in a real browser and verify it
+actually renders:
+
+```bash
+apeironcode test-ui ./my-app
+apeironcode new "todo app" --ui-smoke --yes          # run during creation
+apeironcode new "todo app" --require-ui-smoke --yes  # fail if it can't run/pass
+```
+
+It checks page load, missing assets, console errors, takes a screenshot, and
+runs template-specific interactions (e.g. add a todo and confirm the list
+grows). It needs Chromium (`npx playwright install chromium`); without a
+browser it reports **skipped**, never a fake pass. See
+[ui-smoke.md](./ui-smoke.md). UI smoke is not a full QA replacement.
+
+## Safety
+
+- App creation is **approval-gated**: you see a bundle (directory + files +
+  validation) before anything is written. Auto-approved only in bypass/trusted
+  mode or with `--yes`.
+- A **non-empty directory** is never written into without `--overwrite`, and
+  even then **existing files are never replaced** — only new files are added.
+- Files are only ever written inside the chosen app directory; `.git` and
+  `.env` are never written.
+- Validation commands use the central command policy. Network is off by
+  default, Docker is used when available/configured, and native fallback is not
+  described as OS-isolated.
+- `--dry-run` shows the plan and writes nothing.
+
+## Limitations (alpha)
+
+- Static templates are the most reliable. Vite is alpha and needs a manual
+  install/build. Next.js is not implemented yet.
+- These are prototypes, not production apps. Use `apeironcode improve` and
+  `apeironcode fix` to iterate.
-Original file line number
+Diff line change
@@ Expand Up @@
     # → selects: security-reviewer, reviewer
     ```
-    In VS Code, use **ApeironCode: Route Prompt to Brain** or the **Route Prompt** button in the Project Brain panel.
     ## Commands
     ```bash
@@ Expand Down @@