Sharpen product narrative and README

README.md

@@ -1,29 +1,30 @@
 # ArchCode
 
-> **An open-source cloud workbench for AI coding.**
+> **The open-source workbench for AI coding.**
 
-Self-host it on your own machine or server. Capture ideas as Todos, run
-specialized Agents, and manage their work from any browser.
+Capture project work as durable Todos, carry it out in one or more inspectable
+Agent Sessions, and review the evidence before you mark it done. Self-host
+ArchCode on your machine or server and connect the model providers you choose.
 
-[![ArchCode project workbench demo](docs/assets/archcode-readme-demo.gif)](docs/assets/archcode-readme-demo.mp4)
+[![ArchCode Todo workbench with example project work](docs/assets/archcode-readme-workbench.jpg)](docs/assets/archcode-readme-workbench.jpg)
 
-*A 15-second tour from Project Todos to multiple Sessions, human decisions, and
-verified results. Click for the full-resolution MP4.*
+*Ideas, ready work, active work, and completed work stay visible in one Project.*
 
-## Give every project idea somewhere to go
+## How ArchCode works
 
-1. **Capture an idea** — save anything you may want to build, fix, investigate,
-   or improve as a Project Todo.
-2. **Shape the work** — discuss the Todo with an Agent until the scope and
-   expected outcome are clear; generate or refine its single Markdown Plan when
-   the work needs one.
-3. **Mark it Ready** — keep rough ideas separate from work that is ready to run.
-4. **Start the work** — launch a fresh Lead Session or an Automation from the
-   Todo.
-5. **Review the result** — follow the work, handle decisions, inspect the
-   evidence, and mark the Todo Done.
+1. **Capture a Todo** — record something you want to build, fix, investigate, or
+   improve in an existing Project.
+2. **Shape it when useful** — open a dedicated Discussion to clarify the work,
+   and keep an optional Markdown Plan with the Todo.
+3. **Run the work** — start one or more Lead Sessions, or create an Automation
+   to start it once later or on a recurring schedule.
+4. **Stay involved** — follow the work, add instructions, answer questions, and
+   approve sensitive actions from the Web workbench.
+5. **Review and finish** — inspect changes, tool output, tests, and Session
+   history, then decide when the Todo is Done.
 
-Project Todos are optional. You can always start an ordinary Session directly.
+Use **Run now** to create a Todo and start its first Session in one step, without
+a Discussion or Plan. You can also start an ordinary Session without a Todo.
 
 ## Quick start
 
@@ -53,25 +54,47 @@ workbench with a password.
 
 ### 4. Add a project
 
-Choose an existing project directory. Capture an idea as a Todo or start a
+Choose an existing project directory. Capture project work as a Todo or start a
 Session directly. ArchCode works with the files and Git repository already on
 the machine where it runs.
 
 Need another platform, manual verification, or a remote deployment? See the
 [installation](docs/installation.md) and [deployment](docs/deployment.md)
 guides.
 
-## Keep multiple pieces of work moving
+## Keep project work organized
+
+A Todo gives each feature, bug, refactor, experiment, or investigation a durable
+place in its Project. Keep the request, lifecycle, acceptance criteria,
+references, and optional Markdown Plan together as the work moves from Idea to
+Ready, In Progress, and Done.
+
+[![ArchCode Todo detail with lifecycle, content, acceptance criteria, references, and related work](docs/assets/archcode-readme-todo-detail.jpg)](docs/assets/archcode-readme-todo-detail.jpg)
+
+*A Todo detail keeps the request, lifecycle, acceptance criteria, references,
+and related work together.*
 
 Register multiple existing workspaces and return to them from the same Web
-workbench. Within each Project, keep multiple Sessions for different pieces of
-work. Each Session retains its own conversation, model selection, working
-directory, tool activity, approvals, execution state, and history.
+workbench. Start multiple Sessions from a Todo when the work needs separate
+investigation, implementation, or review without mixing everything into one
+conversation.
+
+## Inspect and control every Session
 
-Work on a feature, investigate a bug, review a change, and shape the next idea
-without mixing everything into one conversation.
+Each Session keeps its own conversation, selected model, working directory,
+tool activity, approvals, execution state, and history. Follow active work, add
+instructions, queue the next message, answer questions, approve sensitive
+actions, or stop an Execution.
 
-## Specialized Agents, clear responsibilities
+[![ArchCode Work Session with Lead, Analyst, and Build Agents](docs/assets/archcode-readme-session-agents.jpg)](docs/assets/archcode-readme-session-agents.jpg)
+
+*The Lead coordinates an Analyst and a Build Agent while each Agent's work
+remains individually inspectable.*
+
+Before accepting the result, inspect file changes, tool output, test results,
+review summaries, and the complete Session history.
+
+### Specialized Agents, clear responsibilities
 
 | Agent | Responsibility | Model Profile |
 |---|---|---|
@@ -85,87 +108,44 @@ without mixing everything into one conversation.
 The Lead delegates bounded responsibilities when specialized work is useful.
 Each Agent identity has its own tools, delegation rules, and authority.
 
-## Different jobs. Different models.
-
-ArchCode separates Agent responsibility from model choice. Configure
-`principal`, `deep`, and `fast` Profiles, then use stronger models where
-judgment matters and fast or local models for exploration and routine work.
-
-Connect official AI SDK providers, custom OpenAI-compatible endpoints, or
-Responses-compatible endpoints. A user-facing root Session can also override
-its model without changing the Agent's tools or responsibility. See [provider and model
-configuration](docs/configuration.md).
-
-MCP servers are configured live under `mcp.servers`: every server requires
-`type` (`http` or `stdio`) and `enabled`. HTTP servers use `url` and optional
-`headers`; STDIO servers use `command` plus optional `args` and `env`. Optional
-`connectTimeoutMs`, `discoveryTimeoutMs`, and `callTimeoutMs` replace the old
-single `timeout`, while `mcp.disabledBuiltins` disables selected built-ins. See
-[GitHub and MCP integrations](docs/integrations.md) for the complete schema.
-
-## Stay in control
-
-Follow active work from the Web workbench, add instructions while it runs, queue
-the next message, answer questions, approve sensitive actions, or stop an
-Execution.
+## Self-host the runtime and choose the models
 
-Before accepting the result, inspect file changes, tool output, test results,
-review summaries, and the complete Session history. Work runs on the ArchCode
-host rather than in the browser, so closing the page does not cancel an active
+Run ArchCode on a laptop, workstation, Mac mini, home server, or VPS. The same
+server runtime and Web UI work in every deployment, and active work runs on the
+ArchCode host rather than in the browser. Closing the page does not cancel an
 Execution while the process and machine remain running.
 
-## Goals and Automations
-
-Use a Goal when the same Lead needs to stay focused on an objective across
-multiple Executions and human checkpoints. A Goal completes only after its
-required review gate.
-
-Use an Automation when work should start once or on a recurring schedule. Goals
-and Automations are optional; both remain visible through Sessions inside the
-same workbench.
-
-## Durable, inspectable memory
-
-ArchCode keeps personal preferences and project knowledge as ordinary Markdown.
-Explicit requests to remember something are saved immediately through the
-Memory tool. Other durable context is considered only after a successful root
-conversation has been idle for 10 minutes, then reconciled against the complete
-Memory files it actually affects. Settings → Memory lets you inspect, edit,
-delete, disable recall, or opt out of automatic learning without deleting data.
-
-## Run it your way
-
-| Where ArchCode runs | Good for | How you open it |
-|---|---|---|
-| Laptop | The fastest way to try ArchCode and work with local projects | `http://localhost:4096` |
-| Workstation or Mac mini | More compute, local-network access, or an always-on personal machine | A browser on the same machine or trusted network |
-| Home server or VPS | Remote access and long-running work on a machine that stays online | HTTPS or a trusted reverse proxy |
-
-ArchCode uses the same server runtime and Web UI in every deployment. You
-choose where it runs.
-
-## A native Agent runtime
-
 ArchCode runs its own Agent loop rather than remotely controlling an existing
 Claude Code, Codex, or another coding CLI process. Its server owns Agent
 execution, projects, Sessions, tools, approvals, memory, and durable state. The
 browser is the control interface, not the place where the Agent runs.
 
+ArchCode separates Agent responsibility from model choice. Connect official AI
+SDK providers, custom OpenAI-compatible endpoints, or Responses-compatible
+endpoints. Configure `principal`, `deep`, and `fast` Profiles, then use stronger
+models where judgment matters and fast or local models for exploration and
+routine work. See [provider and model configuration](docs/configuration.md).
+
 ArchCode does not claim to make the underlying model smarter. It gives models a
 self-hosted runtime, specialized responsibilities, and a persistent project
 workbench.
 
-## Built in
+## More built in
 
 - Structured file, shell, Git, search, LSP, Web, memory, and MCP tools
 - Built-in and project workflow Skill packages for Todo shaping, planning,
   review, and repeatable working methods
-- Project memory and context compaction
+- Automations that start or resume work once or on a recurring schedule
+- Optional Goals that keep one Lead focused across multiple Executions and
+  human checkpoints, with a required final review
+- Inspectable Markdown memory and context compaction
 - Optional Git worktree execution
-- GitHub plus live HTTP/STDIO MCP integrations, with every enabled user server available to all Agents
+- GitHub plus live HTTP/STDIO MCP integrations
 - Signed direct updates with an idle-only graceful restart
 
-Learn the product vocabulary in [workbench concepts](docs/concepts.md).
+Learn the product vocabulary in [workbench concepts](docs/concepts.md), and see
+[GitHub and MCP integrations](docs/integrations.md) for the complete integration
+schema.
 
 ## Know before you self-host
 

docs/concepts.md

@@ -1,24 +1,50 @@
 # Workbench concepts
 
-ArchCode organizes AI coding work around Projects, Project Todos, and persistent
-Sessions. Capture and shape an idea as a Todo, start the work in a Session, and
-keep its execution history and human decisions together. You can also start
-with an ordinary Session and adopt the other concepts only when they solve a
-real need.
+ArchCode is an open-source, self-hosted workbench for AI coding. Projects
+contain Todos, Sessions, and Automations. A Todo records project work you want
+done. A Session is where an Agent discusses or carries out that work. An
+Automation starts work once or on a recurring schedule. Use these concepts
+together, or start an ordinary Session directly.
 
 ## Project
 
-A Project registers an existing absolute workspace directory on the machine
-running ArchCode. It keeps that workspace's ideas, active work, history, and
-control surfaces together through Sessions, Todos, Automations, approvals, and
-project-scoped memory.
+A Project is an existing workspace directory registered on the machine running
+ArchCode. Its Todos, Sessions, Automations, approvals, history, and
+project-scoped memory stay together in the workbench.
+
+## Todo
+
+A Project Todo records one piece of work you may want to build, fix,
+investigate, or improve. A new Todo starts as an Idea. You can open a dedicated
+Discussion to clarify it, attach an optional Plan, and move it among Idea,
+Ready, In Progress, and Done. Rejected and Archived remain outside the main
+workflow.
+
+When a Todo needs a Plan, **Generate / Improve Plan** reuses its latest
+Discussion only when that Session is idle and maintains one ordinary Markdown
+file at `.archcode/plans/<todo-id>.md`. If no Discussion exists, the latest one
+is busy or suspended, it was deleted, or an idle reuse loses the acceptance
+race, ArchCode creates a new Discussion with Plan work as its first message.
+The UI never races a generic Discussion execution with a second Plan command.
+A Ready or In Progress Todo can start any number of fresh ordinary Lead work
+Sessions or an Automation setup Session. At that one start boundary, ArchCode
+checks whether the Plan file exists: if it does, the Lead begins with
+`execute-plan`; otherwise it follows the ordinary work path. Starting work from
+Ready moves the Todo to In Progress; opening or continuing an existing Session
+does not change the Todo. Each direct root Session keeps its own immutable Todo
+source, while an Automation keeps its own optional Todo association. The Todo
+itself never stores Session, Plan, or Automation IDs.
+
+**Run now** creates a minimal In Progress Todo and its first bound Lead Session
+in one step. It skips Discussion and Plan without preventing you from adding
+either later. You can also start a Session directly without creating a Todo.
 
 ## Session
 
-A Session is the durable conversation and execution history for one Agent.
-Ordinary user work starts in a root Lead Session. A Todo Discussion starts in a
-root Discussion Session dedicated to shaping that Todo and its optional Plan.
-The Session keeps its model Profile, working directory, messages, tool activity,
+A Session contains one Agent's conversation and execution history. Ordinary
+user work starts in a root Lead Session. A Todo Discussion starts in a root
+Discussion Session dedicated to shaping that Todo and its optional Plan. The
+Session keeps its model Profile, working directory, messages, tool activity,
 approvals, and terminal state.
 
 ## Execution
@@ -44,29 +70,11 @@ Reasoning usage belongs to its individual model attempt, never to a synthetic
 Execution-wide Reasoning item. Segments are independent display and navigation
 projections only: they do not create, persist, or schedule Executions.
 
-## Todo
-
-Project Todos are optional, project-owned entries for anything you may want to
-build, fix, investigate, or improve. A new Todo starts as an Idea. You can open
-a dedicated Discussion to clarify and shape it, then freely organize it among
-Idea, Ready, In Progress, and Done; Rejected and Archived are separate from the
-main board.
+## Automation
 
-When a Todo needs a Plan, **Generate / Improve Plan** reuses its latest
-Discussion only when that Session is idle and maintains one ordinary Markdown
-file at `.archcode/plans/<todo-id>.md`. If no Discussion exists, the latest one
-is busy or suspended, it was deleted, or an idle reuse loses the acceptance
-race, ArchCode creates a new Discussion with Plan work as its first message.
-The UI never races a generic Discussion execution with a second Plan command.
-A Ready or In Progress Todo can start any number of fresh
-ordinary Lead work Sessions or an Automation setup Session. At that one start
-boundary, ArchCode checks whether the Plan file exists: if it does, the Lead
-begins with `execute-plan`; otherwise it follows the ordinary work path.
-Starting work from Ready moves the Todo to In Progress; opening or continuing
-an existing Session does not change the Todo. Each direct root Session keeps
-its own immutable Todo source, while an Automation keeps its own optional Todo
-association. The Todo itself never stores Session, Plan, or Automation IDs. You
-can also start a Session directly without creating a Todo.
+An Automation starts or resumes project work once or on a recurring schedule.
+It creates a root Lead Session or sends a message to an existing Session; it
+does not replace a Session or own the conversation.
 
 ## Goal
 
@@ -78,12 +86,6 @@ only after the required review gate.
 
 Ordinary requests do not create Goals automatically.
 
-## Automation
-
-An Automation is a durable schedule that starts ordinary Sessions for a
-project. It is useful for recurring work; it does not replace a Session or own
-the conversation.
-
 ## Agent identities
 
 ArchCode ships with five execution and collaboration identities plus a dedicated

package.json

@@ -2,7 +2,7 @@
   "name": "archcode",
   "version": "0.0.9",
   "private": true,
-  "description": "ArchCode — Not just a coding agent. An always-on workbench for AI engineering.",
+  "description": "The open-source, self-hosted workbench for AI coding.",
   "type": "module",
   "packageManager": "bun@1.3.13",
   "workspaces": ["apps/*", "packages/*"],