sneakoscope 0.6.60 → 0.6.64

package/README.md

@@ -2,116 +2,397 @@
 
 ![](https://github.com/mandarange/Sneakoscope-Codex/raw/dev/docs/assets/sneakoscope-codex-logo.png)
 
-Codex CLI/App harness for `$` routes, Team/Ralph/QA/Research, Context7, Honest Mode, DB safety, TriWiki, Codex App skills, and release readiness.
+Sneakoscope Codex (`sks`, displayed as `ㅅㅋㅅ`) is a Codex CLI/App harness for repeatable agent workflows. It adds terminal commands, Codex App `$` prompt commands, cmux-native CLI workspaces, Team/Ralph/QA/Research routes, Context7 evidence checks, DB safety, TriWiki context tracking, Honest Mode, and release-readiness gates.
 
-Install: `npm i -g sneakoscope && sks bootstrap`
-Fallback: `npx -y -p sneakoscope sks bootstrap`
-Project: `npm i -D sneakoscope && npx sks setup --install-scope project`
+## Quick Start
 
-Discover: `sks commands`, `sks dollar-commands`, `sks usage <topic>`
-Check: `sks deps check`, `sks doctor --fix`, `sks selftest --mock`
+Install globally, initialize the current project, then open the cmux runtime:
 
-## What It Adds
+```sh
+npm i -g sneakoscope
+sks bootstrap
+sks
+```
+
+If you only want a one-shot run without keeping `sks` installed globally:
+
+```sh
+npx -y -p sneakoscope sks bootstrap
+```
+
+For a repo-local install:
+
+```sh
+npm i -D sneakoscope
+npx sks setup --install-scope project
+```
 
-Sneakoscope (`sks`, displayed as `ㅅㅋㅅ`) wraps Codex with a repeatable control surface:
+Check that the install is usable:
+
+```sh
+sks deps check
+sks codex-app check
+sks dollar-commands
+sks selftest --mock
+```
+
+## What Sneakoscope Adds
 
 | Area | What it does |
 | --- | --- |
-| Codex App commands | Installs generated skills so `$Team`, `$DFix`, `$QA-LOOP`, `$Ralph`, `$DB`, `$Wiki`, `$Help`, and related routes are discoverable in prompt workflows. |
-| CLI commands | Provides `sks commands`, `sks dollar-commands`, `sks usage <topic>`, bootstrap, setup, doctor, deps, selftest, wiki, team, QA, Ralph, DB, and GX commands. |
-| Team orchestration | Routes substantial code work through ambiguity removal, scouts, TriWiki refresh, debate, consensus, concrete runtime task graph/inboxes, implementation, review, integration, reflection, and Honest Mode. |
-| Ralph | Seals a decision contract up front, then continues without more user questions by using the agreed decision ladder. |
-| QA loop | Dogfoods UI/API behavior with safety boundaries, evidence capture, safe remediation, and focused rechecks. |
-| TriWiki | Keeps `.sneakoscope/wiki/context-pack.json` as the context SSOT, with refresh, pack, prune, validate, active attention ranking, and hydratable source-backed claims. |
-| Context7 | Requires current external library/API/framework docs for routes whose correctness depends on live package or platform behavior. |
-| DB safety | Treats SQL, migrations, Supabase, RLS, and destructive operations as high risk; defaults to inspection and guarded local/branch-safe migration work. |
-| Honest Mode | Finishes work with a claim/evidence pass that separates verified facts, unsupported claims, blocked checks, and not-applicable items. |
-| GX visual context | Generates deterministic visual context cartridges for structured visual review and drift checks. |
-| Research loops | Supports Research and AutoResearch workflows with hypotheses, experiments, falsification, novelty ledgers, SEO/GEO, and evidence-backed conclusions. |
-| Release hygiene | Checks versioning, changelog, package contents, tarball size, syntax, selftests, and dry-run packaging before publish. |
+| CLI runtime | `sks`, `sks cmux`, and `sks --mad --high` open Codex CLI in a cmux workspace. |
+| Codex App commands | Installs generated skills so `$Team`, `$DFix`, `$QA-LOOP`, `$Ralph`, `$DB`, `$Wiki`, `$Help`, and related routes are visible in prompt workflows. |
+| Team orchestration | Runs substantial work through ambiguity handling, scouts, TriWiki refresh, debate, runtime task graphs, worker inboxes, implementation, review, cleanup, reflection, and Honest Mode. |
+| QA loop | Dogfoods UI/API behavior with safety gates, Browser/Computer evidence, safe fixes, and rechecks. |
+| Ralph | Clarifies once, seals a decision contract, then continues without repeatedly asking the user. |
+| TriWiki | Maintains `.sneakoscope/wiki/context-pack.json` as the context SSOT with `attention.use_first` and `attention.hydrate_first`. |
+| Context7 | Requires current docs for external packages, APIs, MCPs, SDKs, and framework/runtime behavior when correctness depends on current guidance. |
+| DB safety | Treats SQL, migrations, Supabase, RLS, and destructive operations as high risk. |
+| Release hygiene | Checks versioning, changelog, package contents, tarball size, syntax, selftests, and dry-run publishing. |
 
-## Prompt `$` Commands
+## Requirements
 
-Use these inside Codex App or another agent prompt. They are prompt commands, not terminal commands.
+- Node.js `>=20.11`
+- npm
+- Codex CLI for terminal workflows
+- Codex App for app-facing workflows and first-party Browser Use / Computer Use parity
+- cmux for the CLI-first runtime
+- Context7 MCP for current-docs-gated routes
 
-| Prompt | Purpose |
-| --- | --- |
-| `$Team` | Default route for code-changing work and substantial implementation. |
-| `$From-Chat-IMG` | Team alias for chat screenshot plus original attachment intake. |
-| `$DFix` | Tiny design/content fixes: labels, copy, colors, spacing, translation. |
-| `$Answer` | Answer-only route when no implementation should start. |
-| `$SKS` | Setup, status, usage, and Sneakoscope workflow help. |
-| `$QA-LOOP` | UI/API dogfooding, safe fixes, and rechecks. |
-| `$Ralph` | Clarify once, seal a decision contract, then execute. |
-| `$Research` | Frontier-style research with hypotheses and falsification. |
-| `$AutoResearch` | Iterative improve-test-keep/discard optimization loop. |
-| `$DB` | Database and Supabase safety checks. |
-| `$MAD-SKS` | Explicit scoped DB authorization modifier; combine it with another `$` route when needed, widened Supabase MCP permissions last only for that invocation, and table deletion requires a short user confirmation timeout. |
-| `$GX` | Deterministic visual context generation and validation. |
-| `$Wiki` | TriWiki refresh, pack, prune, validate, and maintenance. |
-| `$Help` | Installed command and workflow explanation. |
-
-Run `sks dollar-commands` to verify the terminal and Codex App command surfaces agree.
-
-## Terminal Examples
+On macOS, `sks --mad --high` can install cmux through Homebrew when cmux is missing. You can also install it manually:
+
+```sh
+brew tap manaflow-ai/cmux
+brew install --cask cmux
+```
+
+If the CLI is not on `PATH`, SKS also checks the app bundle path:
+
+```sh
+/Applications/cmux.app/Contents/Resources/bin/cmux
+```
+
+## Installation
+
+### Global Install
+
+Use this when you want `sks` available from any repo:
+
+```sh
+npm i -g sneakoscope
+sks bootstrap
+```
+
+`sks bootstrap` initializes the current project, installs Codex App skills/hooks/config, checks Context7/Codex App/cmux readiness, and prints a ready status.
+
+### One-Shot Install
+
+Use this when you do not want to keep a global install:
+
+```sh
+npx -y -p sneakoscope sks bootstrap
+```
+
+`npx` fetches the package into npm's cache and runs the binary for that command. This is useful for first-time setup or CI-style verification.
+
+### Project Install
+
+Use this when a repo should pin Sneakoscope as a development dependency:
+
+```sh
+npm i -D sneakoscope
+npx sks setup --install-scope project
+```
+
+Project installs are useful when a team wants a repeatable harness version checked through `package-lock.json`.
+
+### Source Checkout
+
+Use this when developing Sneakoscope itself:
 
 ```sh
+git clone https://github.com/mandarange/Sneakoscope-Codex.git
+cd Sneakoscope-Codex
+npm install
+npm install -g .
+sks --version
+```
+
+## Terminal CLI Usage
+
+Use terminal commands when you want to inspect, set up, verify, or start a CLI-first workspace.
+
+### Discovery
+
+```sh
+sks commands
 sks usage install
 sks usage team
-sks usage qa-loop
 sks usage codex-app
-sks setup --install-scope project
+sks dollar-commands
+sks --version
+```
+
+### Setup And Repair
+
+```sh
+sks bootstrap
+sks deps check
+sks deps install cmux
+sks codex-app check
+sks doctor --fix
+sks fix-path
+```
+
+### Open Codex CLI With cmux
+
+```sh
+sks
+sks cmux check
+sks cmux status --once
+```
+
+`sks` opens a cmux workspace for Codex CLI when running in an interactive terminal. `sks cmux check` is diagnostic and prints readiness without starting a workspace.
+
+### MAD High cmux Workspace
+
+```sh
+sks --mad --high
+```
+
+This creates/uses the `sks-mad-high` Codex profile for a one-shot full-access, high-reasoning cmux workspace. It is scoped to that explicit command and does not change normal SKS/DB safety defaults.
+
+### Team Missions
+
+```sh
+sks team "implement this feature" executor:3 reviewer:1
+sks team watch latest
+sks team status latest
+sks team log latest
+```
+
+Team mode prepares the mission, records live events, compiles runtime tasks and worker inboxes, and opens cmux live lanes when cmux is available.
+
+### QA, Ralph, Research, DB, Wiki, GX
+
+```sh
+sks qa-loop prepare "http://localhost:3000"
+sks qa-loop run latest --max-cycles 2
+sks ralph prepare "migrate this workflow without asking after prepare"
+sks research prepare "evaluate this approach"
+sks db scan --json
 sks wiki refresh
 sks wiki validate .sneakoscope/wiki/context-pack.json
-sks versioning status
+sks gx init homepage
+sks gx render homepage --format html
 ```
 
-Route examples:
+## Codex App Usage
+
+Sneakoscope has two surfaces:
+
+- Terminal commands such as `sks deps check`, `sks team "task"`, and `sks --mad --high`
+- Codex App prompt commands such as `$Team`, `$DFix`, `$QA-LOOP`, and `$Wiki`
+
+After installing, run:
 
 ```sh
-sks team "implement this" executor:3 reviewer:1
-sks team watch <mission-id>
-sks qa-loop prepare
-sks qa-loop run
-sks ralph prepare
-sks ralph run
-sks db scan
-sks gx init
+sks bootstrap
+sks codex-app check
+sks dollar-commands
+```
+
+Then open Codex App and use prompt commands directly in the chat. Examples:
+
+```text
+$Team implement the checkout fix and verify it
+$DFix change this label and spacing only
+$QA-LOOP dogfood localhost:3000 and fix safe issues
+$Ralph clarify once, then finish the migration without more questions
+$Wiki refresh and validate the context pack
+$DB inspect this migration for destructive risk
 ```
 
-## Workflow Rules
+Generated app files include:
+
+| Path | Purpose |
+| --- | --- |
+| `.codex/SNEAKOSCOPE.md` | Codex App quick reference and route guidance. |
+| `.agents/skills/` | Generated skill instructions for `$` commands. |
+| `.codex/hooks.json` | Stop/finalization hooks for Honest Mode and completion summaries. |
+| `.codex/config.toml` | Codex profiles, agents, and MCP configuration. |
+| `.sneakoscope/` | Runtime state, missions, wiki packs, policies, and artifacts. |
+
+Use `sks dollar-commands` to confirm that terminal discovery and Codex App prompt commands agree.
 
-For code work, Sneakoscope defaults to Team. The normal flow is: remove ambiguity that can change scope or safety, read/validate TriWiki, consume `attention.use_first` for compact high-trust context, hydrate `attention.hydrate_first` from source before risky decisions, gather current source evidence, synthesize consensus, compile a concrete runtime task graph plus worker inboxes, implement bounded changes, refresh/validate context after meaningful findings, run relevant checks, then finish with reflection and Honest Mode.
+## Prompt `$` Commands
 
-For tiny text/design edits use `$DFix`. For questions that should not change files use `$Answer`.
+Use these inside Codex App or another agent prompt. They are prompt commands, not terminal commands.
 
-## Codex App Surface
+| Prompt | Use when |
+| --- | --- |
+| `$Team` | You want implementation, code changes, or substantial repo work. |
+| `$From-Chat-IMG` | You have a chat screenshot plus original attachments and want each visible request mapped to work. |
+| `$DFix` | You need a tiny design/content edit such as copy, label, color, spacing, or translation. |
+| `$Answer` | You want an answer only and no implementation should start. |
+| `$SKS` | You need setup, status, usage, or workflow help. |
+| `$QA-LOOP` | You want UI/API dogfooding, safe fixes, and rechecks. |
+| `$Ralph` | You want one prepare-time clarification pass, then no more user questions. |
+| `$Research` | You need frontier-style research with hypotheses and falsification. |
+| `$AutoResearch` | You want iterative improve/test/keep-or-discard optimization. |
+| `$DB` | You need database, Supabase, migration, SQL, or MCP safety checks. |
+| `$MAD-SKS` | You explicitly authorize a scoped high-risk DB permission modifier for the active invocation only. |
+| `$GX` | You need deterministic visual context cartridges. |
+| `$Wiki` | You want TriWiki refresh, pack, prune, validate, or maintenance. |
+| `$Help` | You want installed command and workflow explanation. |
 
-`sks bootstrap` and `sks setup` install `.codex/SNEAKOSCOPE.md`, generated `.agents/skills`, `.codex/hooks.json`, route instructions for `$` commands, and user-home skill state for first-install discoverability.
+## Common Workflows
 
-After install, check:
+### First Install Checklist
 
 ```sh
+npm i -g sneakoscope
+sks bootstrap
+sks deps check
+sks codex-app check
 sks dollar-commands
-sks usage codex-app
+sks selftest --mock
+```
+
+### Start A CLI Workspace
+
+```sh
+sks cmux check
+sks
+```
+
+For the high-reasoning full-access profile:
+
+```sh
+sks --mad --high
+```
+
+### Use Codex App `$Team`
+
+```text
+$Team implement the requested change, update docs if needed, and verify with the relevant tests
+```
+
+Team mode records a mission under `.sneakoscope/missions/`, keeps a live transcript, uses TriWiki context, and finishes with evidence and Honest Mode.
+
+### Dogfood A UI Or API
+
+```sh
+sks qa-loop prepare "http://localhost:3000"
+sks qa-loop run latest --max-cycles 2
+sks qa-loop status latest
 ```
 
-## Release Checks
+Use `$QA-LOOP` in Codex App when Browser Use or Computer Use evidence should be part of the workflow.
 
-Before publish:
+### Refresh Context Before Risky Work
+
+```sh
+sks wiki refresh
+sks wiki validate .sneakoscope/wiki/context-pack.json
+```
+
+TriWiki is the long-running context source of truth. It keeps compact high-trust recall in `attention.use_first` and source-hydration targets in `attention.hydrate_first`.
+
+## Safety Model
+
+Sneakoscope intentionally treats these as high-risk:
+
+- SQL and migrations
+- Supabase MCP and RLS changes
+- destructive filesystem operations
+- user-global harness config
+- published package/release state
+
+By default, SKS favors inspection, local files, branch-safe changes, explicit confirmation for destructive DB operations, and completion claims backed by tests or artifacts.
+
+## Troubleshooting
+
+### `sks` points to an old version
+
+```sh
+which sks
+sks --version
+node ./bin/sks.mjs --version
+npm install -g .
+```
+
+If the global command is stale, reinstall globally from the repo or from npm.
+
+### cmux is missing
+
+```sh
+sks deps install cmux
+sks cmux check
+```
+
+`sks --mad --high` also attempts Homebrew installation automatically on macOS when cmux is missing.
+
+### Codex App tools are missing
+
+```sh
+sks codex-app check
+codex mcp list
+```
+
+Codex App workflows need the app installed and the first-party Browser Use / Computer Use tools available for parity with QA and visual workflows.
+
+### Setup is blocked by another harness
+
+```sh
+sks conflicts check
+sks conflicts prompt
+```
+
+OMX/DCodex conflicts intentionally block setup/doctor until the user approves cleanup.
+
+### The route is stuck or a final hook keeps reopening
+
+```sh
+sks pipeline status --json
+sks team watch latest
+sks wiki validate .sneakoscope/wiki/context-pack.json
+```
+
+Finalization requires real evidence, no unsupported critical claims, valid Team cleanup artifacts, reflection when required, and Honest Mode.
+
+## Development And Release
+
+Run local checks:
+
+```sh
+npm run repo-audit
+npm run changelog:check
+npm run packcheck
+npm run selftest
+npm run sizecheck
+npm run release:check
+```
+
+Dry-run publish:
 
 ```sh
 npm run publish:dry
 ```
 
-This runs repo audit, changelog check, syntax packcheck, mock selftest, sizecheck, and `npm pack --dry-run`. A dry run proves the local package is packable; npm account ownership or OTP can still block the real registry upload.
+`publish:dry` proves the local package is packable. It does not prove npm ownership, OTP, or registry publish permission.
 
-## Requirements
+## Documentation Style
 
-- Node.js `>=20.11`
-- npm
-- Codex CLI/App for app-facing workflows
-- Context7 MCP for current-docs-gated routes
+This README follows a common open-source CLI shape:
+
+- quick start first
+- explicit install paths
+- separate CLI and app/plugin usage
+- command examples before internal architecture
+- troubleshooting and release checks near the end
+
+That shape mirrors how projects such as `rdme` and Vite separate quick start, setup/configuration, and CLI usage while keeping copy-ready commands visible.
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sneakoscope",
   "displayName": "ㅅㅋㅅ",
-  "version": "0.6.60",
+  "version": "0.6.64",
   "description": "Sneakoscope Codex: database-safe Codex CLI/App harness with Team, Ralph, AutoResearch, TriWiki, and Honest Mode.",
   "type": "module",
   "homepage": "https://github.com/mandarange/Sneakoscope-Codex#readme",
@@ -57,7 +57,7 @@
     "harness",
     "codex-cli",
     "codex-app",
-    "tmux",
+    "cmux",
     "auto-review",
     "browser-use",
     "computer-use",