Less stack-centric and location-centric model.

docs/component-registry.md

@@ -96,13 +96,43 @@ you create live under **`$CASTLE_HOME/code/`** and are recorded as
 the git repo and use the `repo:` prefix. When `castle deploy` writes `castle.yaml`
 back out, it rewrites absolute paths into these relative forms.
 
-### `stack` — Development toolchain
+### `stack` — Development toolchain (optional)
 
 ```yaml
-stack: python-fastapi   # or: python-cli, react-vite
+stack: python-fastapi   # or: python-cli, react-vite — OPTIONAL
 ```
 
-Stacks define how programs get built, checked, and installed.
+A stack provides **default** dev-verb commands (build/test/lint/type-check/…)
+and a scaffold template for new code. It is **optional**: a program with no
+stack works fine as long as it declares its own `commands:`. Stacks are a
+creation-time convenience, not a runtime requirement.
+
+### `commands` — Per-program dev verbs
+
+```yaml
+commands:
+  lint:  [["ruff", "check", "."]]
+  test:  [["pytest", "tests/"]]
+  run:   [["./bin/my-tool", "--serve"]]
+```
+
+Each verb is a list of argv lists (run in sequence). A declared verb **overrides**
+the stack default; an absent verb falls back to the stack handler (if any), else
+the verb is unavailable. `build` is declared via `build:` (it also carries
+`outputs:`); every other verb via `commands:`. This is what lets a wired-in repo
+with no stack be linted/tested/run. Verb resolution lives in
+`core/src/castle_core/stacks.py` (`run_action`, `available_actions`).
+
+### `repo` / `ref` — Wiring in an existing repo
+
+```yaml
+repo: https://github.com/me/widget.git
+ref: v2.1.0          # optional branch/tag/commit
+```
+
+`repo` records a git URL so `castle clone` can provision the source on a fresh
+machine. When `source:` points at an existing working copy, that takes
+precedence. Use `castle add <path|url>` to register an existing repo as a program.
 
 ### `system_dependencies` — Required system packages
 
@@ -111,7 +141,7 @@ system_dependencies: [pandoc, poppler-utils]
 ```
 
 System packages that must be installed for the program to work. Displayed
-in `castle tool list` and the dashboard.
+in `castle list --behavior tool` and the dashboard.
 
 ### `version` — Program version
 

docs/stacks/python-cli.md

@@ -1,5 +1,12 @@
 # Python Tools in Castle
 
+> **This is a stack — creation-time guidance for writing _new_ CLI tools.**
+> A stack is a template + conventions, not a runtime requirement. `castle create
+> --stack python-cli` scaffolds from it and seeds the program's default dev-verb
+> commands. An existing CLI adopted with `castle add` doesn't need this stack — it
+> declares its own `commands:`. See @docs/component-registry.md for `commands:`,
+> `stack:` (optional), and `repo:`.
+
 How to build CLI tools following Unix philosophy.
 
 ## Principles

docs/stacks/python-fastapi.md

@@ -1,5 +1,12 @@
 # Web APIs in Castle
 
+> **This is a stack — creation-time guidance for writing _new_ FastAPI services.**
+> A stack is a template + conventions, not a runtime requirement. `castle create
+> --stack python-fastapi` scaffolds from it and seeds the program's default
+> dev-verb commands. An existing service adopted with `castle add` doesn't need
+> this stack — it declares its own `commands:`. See @docs/component-registry.md
+> for `commands:`, `stack:` (optional), and `repo:`.
+
 How to build Python web APIs as castle service components. Based on the
 patterns used in [wild-cloud/api](https://github.com/civilsociety-dev/wild-cloud)
 and existing castle services (central-context, notification-bridge, event-bus).

docs/stacks/react-vite.md

@@ -1,5 +1,12 @@
 # Web Frontends in Castle
 
+> **This is a stack — creation-time guidance for writing _new_ frontends.**
+> A stack is a template + conventions, not a runtime requirement. `castle create
+> --stack react-vite` scaffolds from it and seeds the program's default dev-verb
+> commands. An existing frontend adopted with `castle add` doesn't need this
+> stack — it declares its own `commands:`. See @docs/component-registry.md for
+> `commands:`, `stack:` (optional), and `repo:`.
+
 How to build, serve, and manage web frontends as castle components.
 
 ## Stack