@geraldmaron/construct 1.0.0 → 1.0.2

package/README.md

@@ -1,344 +1,219 @@
 # Construct
 
-🏢 An org in a box.
+> One AI interface. 28 specialists. Hard gates. Runs locally or deploys for teams.
 
-You say what needs to happen. Construct figures out who handles it, coordinates the work across the right roles, and holds the team accountable until it’s done.
+Construct is a deployable AI R&D operating system. You address one persona — `construct` — in Claude Code, OpenCode, Codex, Cursor, or Copilot. Behind that persona is a team of 28 specialists (architect, engineer, reviewer, QA, security, designer, …) under typed contracts and enforced gates. Sessions survive boundary changes via durable state in `.cx/`, beads, and the vector index. Construct runs locally for individual users (the default) and can be deployed centrally for shared team usage with shared memory, telemetry, queues, and policy.
 
-You don’t manage the handoffs. You don’t direct the agents. You don’t watch the pipeline. You just set the outcome and trust the org to deliver — the same way you’d trust a real team.
+**Full docs:** [`geraldmaron.github.io/construct/v2/`](https://geraldmaron.github.io/construct/v2/) (Phase 1) · while the new docs site is rolling out, the legacy MkDocs site still serves the root URL.
 
-Works with Anthropic, OpenRouter, Ollama, and other OpenAI-compatible setups.
+## Get started in 5 minutes
 
-## 💡 The idea
-
-A real organization doesn’t need its founder to coordinate every interaction between design, engineering, QA, and product. Each role knows its job, challenges the others where it sees a gap, and the system self-corrects.
-
-Construct works the same way.
-
-Under the hood it runs a full specialist team: architects, engineers, designers, reviewers, security, QA, product managers, data analysts, SREs, and more. Each one has domain expertise and a mandate to push back on work that isn’t ready.
-
-You don’t configure any of this. You give Construct a goal and it routes, coordinates, verifies, and ships.
-
-## ✨ What you get
-
-- **Outcome-driven work** — tell it what you want, not which agent to call
-- **A team that challenges itself** — reviewers, security, and QA are peers, not rubber stamps
-- **Workflow state** that persists across sessions and surfaces
-- **Health and visibility** instead of guesswork about what’s running
-- **Telemetry and performance reviews** when you want observability
-- **Cross-tool memory** so work carries across Claude Code, OpenCode, and other surfaces
-- **Hybrid retrieval** over file-state, SQL-ready records, and semantic search
-- **Shared storage setup** that can initialize Postgres and sync core state during `construct setup`
-
-## 📦 Install
-
-### npm
+### Step 1: Install CLI (one-time, per machine)
 
 ```bash
 npm install -g @geraldmaron/construct
-construct setup
 ```
 
-### Homebrew
+### Step 2: Machine Setup (one-time, per machine)
+
+First time on a new machine, bootstrap local services. `construct install` auto-spins local Postgres + telemetry backend via Docker:
 
 ```bash
-brew tap geraldmaron/construct
-brew install construct
-construct setup
+construct install --yes
+# Local services:
+#   Telemetry: http://localhost:54330
+#   Postgres: postgresql://construct:construct@127.0.0.1:54329/construct
 ```
 
-## 🚀 Quick start
-
-`construct setup` bootstraps everything — config, local services, and storage. Once it's done:
+### Step 3: Initialize Project (per project)
 
 ```bash
-construct status   # runtime health
-construct doctor   # installation checks
+cd ~/your-project
+construct init --auto-start
 ```
 
-To initialize a repo for ongoing LLM-assisted work:
+The postinstall hook stages `.construct/` and `.claude/` into your project, so hooks, agents, and slash commands are wired up automatically. Peers who clone your repo and run `npm install` get the same setup with no extra steps.
 
-```bash
-construct init-docs
-```
+Open your editor and address `@construct`. A friendly orientation lives in `construct_guide.md` at your project root.
 
-That creates the core document set Construct expects all LLMs to keep current:
+If you cloned a project that does not yet pin Construct, run `npx -y @geraldmaron/construct init` once to wire it up. No Node at all? `brew install geraldmaron/construct/construct`.
 
-- `.cx/context.md`
-- `.cx/context.json`
-- `.cx/workflow.json`
-- `docs/README.md`
-- `docs/architecture.md`
+[Full 5-minute walkthrough →](https://geraldmaron.github.io/construct/v2/docs/start)
 
-## ⚙️ How it works
+## What you can do with it
 
-Give it a goal. The org handles the rest.
+| If you want to... | Read |
+|---|---|
+| Install + first task | [Start](https://geraldmaron.github.io/construct/v2/docs/start) |
+| Understand how it works | [Concepts → Architecture](https://geraldmaron.github.io/construct/v2/docs/concepts/architecture) |
+| Pick a deployment mode | [Concepts → Deployment model](https://geraldmaron.github.io/construct/v2/docs/concepts/deployment-model) |
+| Drop a signal and triage it | [Concepts → Intake and triage](https://geraldmaron.github.io/construct/v2/docs/concepts/intake-and-triage) |
+| Add a custom specialist | [Cookbook → Add a custom agent](https://geraldmaron.github.io/construct/v2/docs/cookbook/add-a-custom-agent) |
+| Fix a blocked commit or red CI | [Cookbook → Fix a policy violation](https://geraldmaron.github.io/construct/v2/docs/cookbook/fix-a-policy-violation) |
+| Plug in your own LLM | [Cookbook → Plug in your own LLM](https://geraldmaron.github.io/construct/v2/docs/cookbook/plug-in-your-own-llm) |
+| Deploy to AWS | [Cookbook → Deploy to AWS](https://geraldmaron.github.io/construct/v2/docs/cookbook/deploy-to-aws) |
+| Look up a CLI command | [Reference → CLI](https://geraldmaron.github.io/construct/v2/docs/reference/cli) |
+| Recover from an outage | [Operations → Troubleshooting](https://geraldmaron.github.io/construct/v2/docs/operations/troubleshooting) |
 
-```text
-@construct build the customer portal and ship it when it's verified
-@construct fix the login redirect bug
-@construct review the payment flow before release
-@construct explain how the caching layer works
-```
+Works with Anthropic, OpenRouter, Ollama, and other OpenAI-compatible providers.
 
-Construct routes the work, tracks state, verifies outcomes, and follows through.
+## Deployable: solo, team, or enterprise
 
-The team challenges itself along the way — reviewers push back on incomplete work, security flags risky patterns, QA confirms it actually works. You don’t coordinate any of that. You just get the result.
+Construct has three deployment modes. `solo` (the default) runs everything locally — filesystem queue, local repo state, optional Postgres/Docker/telemetry — so if every cloud service goes down you still work from `plan.md`, `.cx/context.md`, beads, git, and the local vector index. `team` promotes the intake queue to Postgres with row-locked worker claims, shares memory across the team, runs workers in a Docker pool, centralizes telemetry, and routes MCP through a broker. `enterprise` adds tenant isolation, RBAC/ABAC scaffolding, isolated worker containers, signed MCP allowlists, and mandatory audit. Pick or change modes with `construct config mode [solo|team|enterprise]`. [Concepts → Deployment model](https://geraldmaron.github.io/construct/v2/docs/concepts/deployment-model).
 
-## 🛠️ Core commands
+## Signals to R&D
 
-<!-- AUTO:commands -->
-### Services
+Anything dropped into `.cx/inbox/` (a bug report, a customer comment, a competitor PDF, a postmortem draft) is classified into an R&D intake type — bug, user-signal, experiment, eval-finding, architecture, incident, security, requirement, research, ops, or legal-compliance — and assigned a primary owner persona with a recommended handoff chain. Inspect with `construct intake list / show <id>`, generate a task graph with `construct graph from-intake <id>`, and update node status with verifiable evidence as work progresses. The classifier is deterministic and runs in the daemon (no LLM); the agent in your editor handles the actual analysis. [Concepts → Intake and triage](https://geraldmaron.github.io/construct/v2/docs/concepts/intake-and-triage).
 
-| Command | What it does |
-|---|---|
-| `construct up` | Start services (memory, dashboard) |
-| `construct down` | Stop all running services |
-| `construct status` | Show canonical system health across runtime and integrations |
-| `construct show` | Show runtime service URLs and live status (compat view) |
-| `construct serve` | Start the Construct dashboard (auto-selects port) |
-| `construct setup` | Bootstrap user config after npm, Homebrew, or manual install |
+## Hard gates
+
+Every code mutation runs through enforcement: no secrets committed, tests green, docs current, comments lint-clean, CI passes. Gates live in three places (write-time, commit-time, CI safety-net) and can only be bypassed with explicit env vars so every exception leaves an audit trail. [Concepts → Gates and enforcement](https://geraldmaron.github.io/construct/v2/docs/concepts/gates-and-enforcement).
 
-### Agents & Sync
+## Core commands
+
+<!-- AUTO:commands -->
+### Core
 
 | Command | What it does |
 |---|---|
-| `construct sync` | Generate agent adapters for all platforms |
-| `construct list` | Show all personas and specialist agents |
+| `construct dev` | Start services for development |
+| `construct docs` | Documentation commands |
+| `construct doctor` | Check installation health |
+| `construct init` | Initialize project and start services |
+| `construct install` | Machine setup: install Docker, cm, and bootstrap config |
+| `construct intake` | View and process R&D intake queue |
+| `construct models` | Manage AI model assignments |
+| `construct recommendations` | View and manage artifact recommendations |
+| `construct status` | Show system health and credentials |
+| `construct stop` | Stop all running services |
+| `construct sync` | Sync agent adapters to AI tools |
 
 ### Work
 
 | Command | What it does |
 |---|---|
-| `construct do` | Execute a natural language goal via the orchestrator |
-| `construct distill` | Distill documents with query-focused, citation-ready chunk selection |
-| `construct research` | Run query-focused bounded retrieval over project documents |
-| `construct docs` | Run documentation-focused bounded retrieval over markdown-like files |
-| `construct search` | Run hybrid file, SQL, and semantic retrieval over core project state |
-| `construct storage` | Sync and inspect the hybrid storage backend |
-| `construct headhunt` | Create a temporary domain expertise overlay or promotion request |
-| `construct workflow` | Manage .cx/workflow.json orchestration state |
-| `construct init-docs` | Generate AI-tailored doc structure for the current project |
-| `construct team` | Team review and template listing |
-
-### Models & Integrations
+| `construct bootstrap` | Import seed observations |
+| `construct customer` | Manage customer profiles for product intelligence |
+| `construct distill` | Distill documents with query-focused chunking |
+| `construct drop` | Ingest file from Downloads/Desktop |
+| `construct graph` | Task graph management |
+| `construct headhunt` | Create domain expertise overlays |
+| `construct infer` | Infer schema from documents |
+| `construct ingest` | Convert documents to indexed markdown |
+| `construct integrations` | Check and manage external system connections |
+| `construct memory` | Inspect memory layer |
+| `construct reflect` | Capture improvement feedback |
+| `construct search` | Hybrid search across project state |
+| `construct storage` | Manage storage backend |
+| `construct team` | Team review and templates |
+| `construct wireframe` | Generate wireframes from description |
+| `construct workspace` | Manage PM workspaces for multi-PM signal routing |
+
+### Integrations
 
 | Command | What it does |
 |---|---|
-| `construct models` | Show or update model tier assignments |
+| `construct claude:allow` | Manage Claude Code permissions |
+| `construct hosts` | Check host capabilities |
 | `construct mcp` | Manage MCP integrations |
-| `construct hosts` | Show host support for Construct orchestration |
+| `construct ollama` | Manage local Ollama models |
+| `construct plugin` | Manage plugin manifests |
 
 ### Observability
 
 | Command | What it does |
 |---|---|
-| `construct review` | Generate agent performance review from Langfuse trace backend |
-| `construct optimize` | Prompt optimization using Langfuse trace quality scores |
-| `construct telemetry-backfill` | Backfill sparse traces with observations (trace backend) |
-| `construct cost` | Show token usage, cost, cache read rate, and per-agent breakdown |
-| `construct efficiency` | Show read efficiency, repeated files, and context-budget guidance |
-| `construct evals` | Show evaluator catalog for prompt and agent experiments |
+| `construct cost` | Token usage and cost breakdown |
+| `construct efficiency` | Read efficiency metrics |
+| `construct evals` | Evaluator catalog |
+| `construct llm-judge` | LLM-as-judge evaluations |
+| `construct optimize` | Prompt optimization |
+| `construct review` | Agent performance review |
 
-### Docs
+### Advanced
 
 | Command | What it does |
 |---|---|
-| `construct docs:update` | Regenerate AUTO-managed regions in README and docs/ |
-| `construct docs:site` | Generate site/docs/ content for the MkDocs GitHub Pages site |
-| `construct lint:comments` | Check all files against the comment policy (rules/common/comments.md) |
-
-### Diagnostics
-
-| Command | What it does |
-|---|---|
-| `construct audit` | Audit Construct internals for gaps or drift |
-| `construct doctor` | Run installation health checks |
-| `construct validate` | Validate registry.json structure and field constraints |
-| `construct diff` | Show which agents changed prompts or settings since HEAD |
+| `construct audit` | Audit Construct internals |
+| `construct auth:status` | Check auth status |
+| `construct backup` | System backups |
+| `construct beads` | Task queue management |
+| `construct cleanup` | Clean stale processes |
+| `construct completions` | Shell completion scripts |
+| `construct config` | Deployment mode configuration |
+| `construct diff` | Show agent changes since HEAD |
+| `construct embed` | Embed mode management |
+| `construct gates:audit` | Audit policy gates |
+| `construct hooks:health` | Check hook health |
+| `construct list` | List all agents |
+| `construct provider` | Provider management |
+| `construct role` | Role framework management |
+| `construct skills` | Skill relevance detection |
+| `construct uninstall` | Remove Construct state |
+| `construct update` | Reinstall this checkout |
+| `construct upgrade` | Upgrade to latest npm version |
+| `construct validate` | Validate registry structure |
 | `construct version` | Show version |
 <!-- /AUTO:commands -->
 
-Use `construct version` to see the installed version.
-
-## 📊 Built for real usage
-
-`construct status` is the main health surface.
-
-It reports what matters now:
-
-- runtime health
-- configured integrations
-- managed dashboard status
-- recent telemetry richness
-- session usage signals when available
-- current workflow/task visibility
-- context/workflow public health in machine-readable form
-- storage mode visibility for file-state, SQL-ready, and vector-ready layers
-
-If you want the raw machine-readable payload:
-
-```bash
-construct status --json
-```
-
-The JSON output includes a shared `publicHealth` block. Today that block exposes:
-
-- `activeTask`
-- `context` (`hasFile`, `source`, `savedAt`, `summary`)
-- `workflow` (`exists`, `phase`, `lifecycleStatus`, `currentTaskKey`, `summary`)
-- `alignment` (`status`, `findings`, counts)
-- `metadataPresence` (`executionContractModel`, `contextState`)
-
-Hybrid storage readiness is also reported via `storage`:
-
-- `sql` (`mode`, `configured`, `sharedReady`, `fallbackAvailable`)
-- `vector` (`mode`, `configured`, `sharedReady`, `fallbackAvailable`)
-- `health` (`sql`, `vector`)
-
-`construct setup --yes` writes managed defaults for local semantic retrieval, starts a localhost-only Postgres container when Docker is running, initializes the schema, and performs an initial file-state sync. If `DATABASE_URL` is already configured, Construct uses that instead of starting managed Postgres.
-
-The status JSON also reports hybrid storage readiness so team-ready deployments can see whether SQL/vector stores are configured or still running file-only. Tracing becomes active once `LANGFUSE_PUBLIC_KEY` and `LANGFUSE_SECRET_KEY` are present in `~/.construct/config.env` or `.env`.
-
-The same public-health contract is exposed through the Construct MCP server on:
-
-- `project_context`
-- `workflow_status`
+## For contributors
 
-The shared contract is strongest around active task, workflow/alignment state, and metadata presence. `project_context` is the MCP surface that also carries the resolved project context payload itself.
+- [`CONTRIBUTING.md`](./CONTRIBUTING.md) — branch workflow, gates, review expectations.
+- [`CHANGELOG.md`](./CHANGELOG.md) — release history.
+- [`docs/concepts/architecture.md`](./docs/concepts/architecture.md) — canonical architecture (rendered on the docs site at [Concepts → Architecture](https://geraldmaron.github.io/construct/docs/concepts/architecture)).
+- [`AGENTS.md`](./AGENTS.md) — agent operating contract.
 
-## 🤖 Bring your own models
-
-Construct is provider-agnostic by design.
-
-You can use:
-
-- Anthropic directly
-- OpenRouter
-- Ollama
-- other compatible endpoints
-
-Set models through environment config, then resync:
-
-```bash
-construct sync
-```
-
-Construct uses three execution tiers:
-
-- `reasoning`
-- `standard`
-- `fast`
-
-It can also infer sibling tiers more intelligently, including optional free-model bias when you want to optimize cost without hand-tuning every tier.
-
-## 🔭 Observability when you want it
-
-Construct uses Langfuse for agent observability.
-
-It supports:
-
-- agent trace creation
-- runtime session telemetry
-- telemetry richness reporting in status/dashboard
-- sparse trace backfill
-- performance reviews
-
-Run `construct setup --yes` to start a local Langfuse instance via Docker, or point to a self-hosted instance by setting `LANGFUSE_BASEURL`, `LANGFUSE_PUBLIC_KEY`, and `LANGFUSE_SECRET_KEY` in `~/.construct/config.env`.
-
-
-## 🧠 Memory across sessions
-
-Construct can use shared memory so work carries across tools and sessions instead of feeling like you’re rebooting your brain every hour.
-
-That is especially useful if you move between OpenCode, Claude Code, and other surfaces.
-
-## 🤝 For contributors
-
-This repo is the source of truth for Construct itself.
-
-To build from source:
-
-```bash
-git clone https://github.com/geraldmaron/construct.git
-cd construct
-npm install && npm install -g .
-construct setup
-```
-
-Important files:
-
-- `agents/registry.json` — core registry and routing source of truth
-- `bin/construct` — CLI entrypoint
-- `lib/` — runtime, hooks, MCP, status, setup, and orchestration logic
-- `personas/` — public/internal prompt surfaces
-- `skills/` — reusable execution knowledge
-- `rules/` — coding and quality guidance
-
-Useful contributor commands:
-
-```bash
-npm test
-node ./bin/construct doctor
-node ./bin/construct status
-node ./bin/construct sync
-node ./bin/construct init-docs
-node ./bin/construct docs:update
-```
-
-Core repo rule:
-
-- treat `.cx/context.*`, `.cx/workflow.json`, `docs/README.md`, and `docs/architecture.md` as shared project state
-- all LLMs working here, including Construct, should read them at session start
-- if work changes project reality, update the affected core document before calling the work done
-
-## Where this is going
-
-Construct is moving toward a package-manager-first, cross-platform setup flow that feels more like a product and less like infra cosplay.
-
-That means:
-
-- `construct setup` is the primary bootstrap path
-- `construct status` is the canonical health surface
-- runtime and telemetry are getting more explicit and less magical
-- public docs present Construct as the product, not a maze of internals
-
-## 📁 Project structure
+## Project structure
 
 <!-- AUTO:structure -->
 ```text
 construct/
 ├── agents           Registry and generated platform adapter chains
+├── apps             User-facing apps shipped from this repo (e.g., apps/docs/ — Fumadocs docs site)
 ├── bin              CLI entrypoint (`construct`)
 ├── commands         Command prompt assets
+├── dashboard
 ├── db
+├── deploy
 ├── docs             Architecture notes, runbooks, and documentation contract
-├── Formula
-├── langfuse         Langfuse trace backend for agent observability
+├── examples
 ├── lib              Core runtime: CLI, hooks, MCP, status, sync, workflow
 ├── personas         Persona prompt definitions
 ├── platforms
+├── providers
 ├── rules            Coding and quality standards
-├── site             MkDocs source for the GitHub Pages documentation site
+├── schemas
+├── scripts
+├── services
 ├── skills           Reusable domain knowledge files
 ├── templates
 ├── tests            Test suite
 ```
 <!-- /AUTO:structure -->
 
-## 🗑️ Uninstall
+## Uninstall
+
+Run the uninstaller first, then drop the package:
 
 ```bash
-npm uninstall -g @geraldmaron/construct
+construct uninstall          # interactive; pick what to remove
+npm uninstall @geraldmaron/construct
 ```
 
-If you installed from source, remove the checkout manually.
+`construct uninstall` probes both project-scope (`.construct/`, the Construct-owned `.claude/agents/` + `.claude/commands/` files, hooks/mcpServers Construct added to `.claude/settings.json`) and machine-scope state (`~/.cx/`, `~/.construct/workspace/`, the embedding model cache, the local Postgres container). Auto-risk items are removed by default; ask-risk items (Postgres data, API keys, AGENTS.md/plan.md you may have edited) are skipped unless you opt in.
+
+It never touches Docker itself, Homebrew CLIs like `cm`/`cass`, the pgvector image, or anything you've added to `.claude/settings.json` by hand. Those appear in the final summary as follow-ups you can run if you want.
 
-Optional local cleanup:
+Useful flags:
 
 ```bash
-rm -rf ~/.construct ~/.cx/performance-reviews
+construct uninstall --dry-run            # show the plan, change nothing
+construct uninstall --yes                # non-interactive, auto-risk only
+construct uninstall --yes --all          # non-interactive, everything
+construct uninstall --scope=project      # only this project; leave ~/.construct alone
+construct uninstall --keep-state         # only .construct/ + .claude/; keep .cx/, ~/.construct, Postgres
 ```
 
 ## License
 
-MIT
+Apache License 2.0. See [`LICENSE`](./LICENSE).