feat(cli): add actor profile surfaces and glossary docs

docs/.vitepress/config.ts

@@ -77,6 +77,14 @@ export default defineConfig({
           items: [
             { text: 'Positioning', link: '/reference/positioning' },
             { text: 'Architecture', link: '/reference/architecture' },
+            { text: 'Local Glossary', link: '/reference/glossary/' },
+            { text: 'Chat Data Flow', link: '/reference/chat-data-flow' },
+            { text: 'Actor Lifecycle Surfaces', link: '/reference/actor-group-lifecycle-surfaces' },
+            { text: 'Actor Terminal Input Control', link: '/reference/actor-terminal-input-control' },
+            { text: 'Actor Native Resume Bindings', link: '/reference/actor-native-resume-bindings' },
+            { text: 'Codex Session Resume', link: '/reference/codex-session-resume' },
+            { text: 'Runtime Session Recovery Strategy', link: '/reference/runtime-session-recovery-strategy' },
+            { text: 'Operations Board and Review', link: '/reference/operations-board-and-review' },
             { text: 'Features', link: '/reference/features' },
             { text: 'CLI', link: '/reference/cli' }
           ]

docs/guide/best-practices.md

@@ -2,6 +2,16 @@
 
 Tips for getting the most out of CCCC.
 
+## Terminology Alignment
+
+This document follows the local glossary:
+
+- `group` is the main collaboration unit
+- `actor` is the live scheduled participant
+- `profile` is reusable actor runtime configuration, not the live actor itself
+- `attach` sets the group's `authoritative_workspace`
+- `status` is an evidence-bound operator-facing surface
+
 ## Setting Up for Success
 
 ### Write a Good PROJECT.md
@@ -116,15 +126,22 @@ Agents read the markdown and follow the rules semantically. There's no special p
 Use recommended flags for autonomous operation:
 
 ```bash
+# Reusable profile-backed setup
+cccc actor profile upsert --id impl-shared --name "Implementer Shared" --runtime claude
+cccc actor add impl --profile-id impl-shared
 # Claude Code
-cccc actor add impl --runtime claude
 # Uses: claude --dangerously-skip-permissions
 
+# Reusable profile-backed setup
+cccc actor profile upsert --id review-shared --name "Reviewer Shared" --runtime codex
+cccc actor add review --profile-id review-shared
 # Codex
-cccc actor add review --runtime codex
 # Uses: codex --dangerously-bypass-approvals-and-sandbox --search
 ```
 
+This keeps reusable runtime intent in `profile` records while leaving the live
+scheduled participant as the `actor`.
+
 ## Effective Communication
 
 ### Be Specific
@@ -254,3 +271,17 @@ If an agent keeps repeating:
 - Check commits before pushing
 - Use code review agents
 - Set up CI/CD guardrails
+
+## Related Glossary
+
+- [group](/reference/glossary/group)
+- [actor](/reference/glossary/actor)
+- [profile](/reference/glossary/profile)
+- [attach](/reference/glossary/attach)
+- [authoritative_workspace](/reference/glossary/authoritative_workspace)
+- [status](/reference/glossary/status)
+
+## Change Log
+
+- `2026-03-23`: Added profile-backed runtime setup examples so best-practice guidance matches the current CLI actor/profile split.
+- `2026-03-23`: Added glossary alignment so best-practice guidance distinguishes live actor behavior from reusable profile configuration and keeps attach/status semantics explicit.

docs/guide/faq.md

@@ -2,6 +2,19 @@
 
 Frequently asked questions about CCCC.
 
+## Terminology Alignment
+
+This document follows the local glossary:
+
+- `group` is the concise repo-local term, while `working group` remains
+  compatibility wording
+- `attach` defines a group's `authoritative_workspace`
+- `scope` is older wording that may still appear in historical answers
+- `profile` means reusable actor runtime configuration and launch intent
+- `status` is an evidence-bound surface, not proof that every deeper capability
+  is available
+- `resume` is layered and does not only mean native runtime session continuity
+
 ## Installation & Setup
 
 ### How do I install CCCC?
@@ -78,6 +91,20 @@ This checks Python version, available runtimes, and daemon status.
 cccc actor add my-agent --runtime custom --command "my-custom-cli"
 ```
 
+### What is the difference between an actor and a profile?
+
+- An `actor` is the live scheduled participant inside a group.
+- A `profile` is reusable runtime configuration that an actor may link to.
+- Linking a profile does not by itself prove that the actor is currently
+  running, resumed, or attached to any particular live session.
+
+Typical profile-backed path:
+
+```bash
+cccc actor profile upsert --id shared-dev --name "Shared Dev" --runtime claude
+cccc actor add dev --profile-id shared-dev
+```
+
 ### Agent won't start?
 
 1. Check the terminal tab for error messages
@@ -198,19 +225,40 @@ cccc doctor                  # Check configuration
 
 ### What is a Working Group?
 
-A working group is like an IM group chat with execution capabilities. It includes:
+A `group` is the core collaboration unit in CCCC. Older FAQ wording may still
+say `working group` for compatibility. It includes:
 - An append-only ledger (message history)
 - One or more actors (agents)
-- Optional scopes (project directories)
+- An attached project path that acts as the group's authoritative workspace
 
 ### What is the Ledger?
 
-The ledger is an append-only event stream that stores all messages, state changes, and decisions. It's the single source of truth for a working group.
+The ledger is an append-only event stream that stores all messages, state
+changes, and decisions. It's the single source of truth for a group.
 
 ### What is MCP?
 
 MCP (Model Context Protocol) is how agents interact with CCCC. It exposes a rich tool surface for messaging, context management, automation, and system control.
 
 ### What is a Scope?
 
-A scope is a project directory attached to a working group. Agents work within scopes, and events are attributed to scopes.
+`Scope` is older compatibility wording for an attached project directory. In
+current glossary terms, `attach` sets the group's
+`authoritative_workspace`, while actor runtimes may later work in the same path
+or a different `execution_workspace` depending on explicit policy.
+
+## Related Glossary
+
+- [group](/reference/glossary/group)
+- [attach](/reference/glossary/attach)
+- [authoritative_workspace](/reference/glossary/authoritative_workspace)
+- [execution_workspace](/reference/glossary/execution_workspace)
+- [profile](/reference/glossary/profile)
+- [resume](/reference/glossary/resume)
+- [status](/reference/glossary/status)
+
+## Change Log
+
+- `2026-03-21`: Added local glossary alignment so FAQ answers stop treating `working group`, `scope`, `status`, and `resume` as self-evident legacy shorthand.
+- `2026-03-23`: Added a concrete profile-management command path so the actor-versus-profile FAQ points to the current CLI surface.
+- `2026-03-23`: Added `profile` alignment and an explicit actor-versus-profile FAQ so reusable runtime configuration is not confused with live actor state.

docs/guide/getting-started/cli.md

@@ -16,6 +16,10 @@ cccc attach .
 
 This binds the current directory as a "scope" and creates a working group.
 
+In current glossary wording, `attach` sets the group's
+`authoritative_workspace`. Older shorthand like `scope` remains compatibility
+wording in some guides and CLI surfaces.
+
 ## Step 3: Configure MCP for Your Runtime
 
 ```bash
@@ -32,6 +36,19 @@ cccc actor add assistant --runtime claude
 
 The first enabled actor automatically becomes the "foreman" (coordinator).
 
+At this step you are creating a live `actor`. Reusable `profile` support is a
+separate concept used when you want runtime defaults or launch intent to be
+reused across actors or later sessions.
+
+If you want that reusable layer first, you can now create it directly from the
+CLI before attaching it to a live actor:
+
+```bash
+cccc actor profile upsert --id shared-codex --name "Shared Codex" --runtime codex
+cccc actor profile list
+cccc actor add assistant --profile-id shared-codex
+```
+
 ## Step 5: Start the Agent
 
 ```bash
@@ -163,7 +180,8 @@ Access at http://127.0.0.1:8848/
 cd ~/projects/my-app
 cccc attach .
 cccc setup --runtime claude
-cccc actor add dev --runtime claude
+cccc actor profile upsert --id dev-shared --name "Dev Shared" --runtime claude
+cccc actor add dev --profile-id dev-shared
 
 # Work
 cccc group start
@@ -219,3 +237,19 @@ cccc attach .
 - [Workflows](/guide/workflows) - Learn collaboration patterns
 - [CLI Reference](/reference/cli) - Complete command reference
 - [IM Bridge](/guide/im-bridge/) - Set up mobile access
+- [Local Glossary](/reference/glossary/) - Canonical local term meanings
+
+## Related Glossary
+
+- [group](/reference/glossary/group)
+- [actor](/reference/glossary/actor)
+- [profile](/reference/glossary/profile)
+- [attach](/reference/glossary/attach)
+- [authoritative_workspace](/reference/glossary/authoritative_workspace)
+
+## Change Log
+
+- `2026-03-21`: Added local glossary alignment so quick-start wording around `attach` points readers to `authoritative_workspace` instead of leaving `scope` ambiguous.
+- `2026-03-23`: Added a concrete `actor add --profile-id ...` quick-start path so profile-backed live actor setup is shown, not just described.
+- `2026-03-23`: Added direct `cccc actor profile ...` quick-start examples so reusable runtime configuration is no longer only described abstractly.
+- `2026-03-23`: Added actor-versus-profile quick-start wording so reusable runtime configuration is not confused with live actor creation.

docs/guide/getting-started/index.md

@@ -2,6 +2,16 @@
 
 Get CCCC running in 10 minutes.
 
+## Terminology Alignment
+
+This page follows the local glossary:
+
+- `group` is the main collaboration unit
+- `actor` is the live scheduled participant
+- `profile` is reusable actor runtime configuration and launch intent
+- `attach` sets the group's `authoritative_workspace`
+- older `scope` wording may still appear as compatibility shorthand
+
 ## Choose Your Approach
 
 CCCC offers two ways to get started:
@@ -100,6 +110,17 @@ cccc doctor
 
 This checks Python version, available runtimes, and system configuration.
 
+If you already know you want reusable runtime intent instead of one-off actor
+creation, the current CLI supports a profile-backed start path:
+
+```bash
+cccc actor profile upsert --id starter-shared --name "Starter Shared" --runtime claude
+cccc actor add starter --profile-id starter-shared
+```
+
+That is the profile-backed setup path. The live scheduled participant is still
+the actor; the profile stores reusable runtime defaults.
+
 ## Next Steps
 
 - [Web UI Quick Start](./web) - Get started with the visual interface
@@ -109,3 +130,16 @@ This checks Python version, available runtimes, and system configuration.
 - [Use Cases](/guide/use-cases) - Learn high-ROI real-world patterns
 - [Operations Runbook](/guide/operations) - Run CCCC with operator-grade reliability
 - [Positioning](/reference/positioning) - Decide where CCCC should sit in your stack
+
+## Related Glossary
+
+- [group](/reference/glossary/group)
+- [actor](/reference/glossary/actor)
+- [profile](/reference/glossary/profile)
+- [attach](/reference/glossary/attach)
+- [authoritative_workspace](/reference/glossary/authoritative_workspace)
+
+## Change Log
+
+- `2026-03-23`: Added a profile-backed setup pointer so the landing page reflects the current actor/profile product split.
+- `2026-03-23`: Added glossary alignment so the main getting-started entry uses repo-local `group` / `actor` / `profile` / `attach` meanings instead of leaving old shorthand implicit.

docs/guide/getting-started/web.md

@@ -2,6 +2,15 @@
 
 Get started with CCCC using the Web interface.
 
+## Terminology Alignment
+
+This document follows the local glossary:
+
+- `attach` sets the group's `authoritative_workspace`
+- `actor` is the live participant you create and start in Web UI
+- `profile` is reusable runtime configuration, separate from the live actor
+- `status` is an evidence-bound operator-facing surface
+
 ## Step 1: Start CCCC
 
 Open a terminal and run:
@@ -35,6 +44,10 @@ cccc attach .
 
 3. Refresh the Web UI to see your new group
 
+In current glossary wording, `attach` sets the group's
+`authoritative_workspace`. That does not by itself create per-actor isolated
+execution workspaces.
+
 ## Step 4: Add Your First Agent
 
 1. Click **Add Actor** in the header
@@ -44,6 +57,18 @@ cccc attach .
    - **Runner**: PTY (terminal) or Headless
 3. Click **Create**
 
+This step creates a live `actor`. In current product terms, any future
+profile-backed Web flow should still be read as linking reusable configuration
+to the actor, not replacing actor identity.
+
+Today, if you want a profile-backed setup before returning to the Web UI, you
+can do it from another terminal:
+
+```bash
+cccc actor profile upsert --id assistant-shared --name "Assistant Shared" --runtime claude
+cccc actor add assistant --profile-id assistant-shared
+```
+
 ## Step 5: Configure MCP (First Time Only)
 
 If this is your first time using CCCC with this runtime:
@@ -155,3 +180,18 @@ Run `cccc attach .` in your project directory, then refresh the Web UI.
 - [Workflows](/guide/workflows) - Learn collaboration patterns
 - [Web UI Guide](/guide/web-ui) - Detailed UI documentation
 - [IM Bridge](/guide/im-bridge/) - Set up mobile access
+- [Local Glossary](/reference/glossary/) - Canonical local term meanings
+
+## Related Glossary
+
+- [actor](/reference/glossary/actor)
+- [profile](/reference/glossary/profile)
+- [attach](/reference/glossary/attach)
+- [authoritative_workspace](/reference/glossary/authoritative_workspace)
+- [status](/reference/glossary/status)
+
+## Change Log
+
+- `2026-03-21`: Added local glossary alignment so Web quick-start wording distinguishes group attachment from future execution-workspace policy.
+- `2026-03-23`: Added a profile-backed setup note so Web quick-start reflects the current CLI actor/profile surface.
+- `2026-03-23`: Added actor-versus-profile quick-start wording so Web setup does not collapse reusable runtime configuration into live actor creation.

docs/guide/group-space-notebooklm.md

@@ -2,6 +2,15 @@
 
 This guide covers the user-facing Web flow for connecting NotebookLM and choosing which notebooks CCCC should use.
 
+## Terminology Alignment
+
+This document follows the local glossary:
+
+- `group` remains the lifecycle owner of notebook binding state
+- `attach` sets the group's `authoritative_workspace`
+- `status` on this page should be read as a lightweight operator-facing snapshot
+- provider binding state does not replace group/runtime truth
+
 The Web UI is intentionally minimal:
 
 1. connect Google
@@ -127,3 +136,14 @@ Relevant metadata files remain:
 - `<scope_root>/space/artifacts/notebooklm/...`
 
 These implementation details matter for agent/developer workflows, but they are not part of the normal user-facing binding flow.
+
+## Related Glossary
+
+- [group](/reference/glossary/group)
+- [attach](/reference/glossary/attach)
+- [authoritative_workspace](/reference/glossary/authoritative_workspace)
+- [status](/reference/glossary/status)
+
+## Change Log
+
+- `2026-03-23`: Added glossary alignment so NotebookLM binding guidance keeps group ownership, attach authority, and lightweight status semantics explicit.