docs: align project init showcase with spec

docs/showcase/cli-tools/project-init-and-context-management.md

@@ -2,109 +2,129 @@
 
 ## Overview
 
-This example demonstrates how to initialize a CleverAgents project, manage namespaced projects, add files to context, and work with interactive sessions — all from the command line. You'll learn the complete project lifecycle from `init` through `project create`, `project list`, `project show`, and context management.
+This showcase walks through the **specification-aligned** workflow for bringing a
+new CleverAgents workspace online, registering a project, and configuring the
+Advanced Context Management System (ACMS) policy that governs what information
+flows into your actors. You will also verify the active context, simulate a
+context window, and finish by inspecting session activity.
 
 ## Prerequisites
 
 - CleverAgents installed (`pip install cleveragents`)
-- Python 3.12 or higher
+- Python 3.13 or higher
 
 ## What You'll Build
 
-A fully initialized CleverAgents workspace with:
-- A project directory with `.cleveragents/` data store (SQLite database, config, and directory structure)
-- One or more named projects in the `local/` namespace
-- Files added to the active context for AI-assisted work
-- An interactive session ready for actor-driven tasks
+- A freshly initialised CleverAgents workspace seeded with the `.cleveragents`
+  data store
+- A namespaced project (`local/my-webapp`) registered in the catalogue
+- A strategize-phase context policy that filters paths and enforces ACMS
+  budgets
+- Verified context metrics, a dry-run context simulation, and a recorded
+  interactive session
 
 ---
 
 ## Step-by-Step Walkthrough
 
-### Step 1: Initialize a New Project
+### Step 1: Initialise the Workspace
 
-Create a fresh directory and initialize CleverAgents inside it:
+Create a new directory and run the spec-defined `agents init` command in
+non-interactive mode to bootstrap the data store.
 
 ```bash
 $ mkdir my-workspace && cd my-workspace
-$ python -m cleveragents project init my-workspace --yes
+$ agents init --yes
 ```
 
 **Expected Output:**
 ```
-╭──────────────────────────────────────────────────────────────╮
-│ Data Dir: /path/to/my-workspace/.cleveragents (created)      │
-│ Config: /path/to/my-workspace/.cleveragents/config.toml      │
-│ Database: initialized (schema v3)                            │
-│ Directories: logs, cache, sessions, contexts                 │
-╰──────────────────────────────────────────────────────────────╯
+╭────────────────────────── Initialized ──────────────────────────╮
+│ Data Dir: /path/to/my-workspace/.cleveragents (created)         │
+│ Config:   /path/to/my-workspace/.cleveragents/config.toml       │
+│ Database: initialized (schema v3)                              │
+│ Directories: logs, cache, sessions, contexts                    │
+╰────────────────────────────────────────────────────────────────╯
 ✓ OK Initialized (non-interactive)
 ```
 
 **What's Happening:**
-CleverAgents creates a `.cleveragents/` directory inside your workspace with a SQLite database (schema v3), a TOML configuration file, and four subdirectories: `logs/`, `cache/`, `sessions/`, and `contexts/`. The `--yes` flag skips interactive prompts, making it ideal for scripting and CI/CD pipelines.
+`agents init` performs a **destructive reset** of the `.cleveragents/`
+directory: it snapshots the existing data set, wipes the on-disk database, and
+then recreates the schema alongside the cache/session/context folders. Using
+`--yes` bypasses the danger prompt so automation pipelines can proceed without
+interactive confirmation—omit `--yes` when running manually if you want the
+CLI to pause before erasing an existing workspace.
 
 ---
 
-### Step 2: Create a Named Project
+### Step 2: Create a Namespaced Project
 
-Projects in CleverAgents use a `namespace/name` format. The `local/` namespace is the default for user-created projects:
+Register a project using the canonical `namespace/name` format.
 
 ```bash
-$ python -m cleveragents project create local/my-webapp --description "A sample web application project"
+$ agents project create local/my-webapp --description "A sample web application project"
 ```
 
 **Expected Output:**
 ```
-╭─────────────────────────────────────────────╮
-│ ✓ Project 'local/my-webapp' created.        │
-│ Namespace: local                            │
-│ Description: A sample web application project│
-│ Resources: 0                                │
-╰─────────────────────────────────────────────╯
+╭───────────────────────── Project Created ───────────────────────╮
+│ ✓ Project 'local/my-webapp' created.                             │
+│ Namespace: local                                                 │
+│ Description: A sample web application project                    │
+│ Resources: 0                                                     │
+╰────────────────────────────────────────────────────────────────╯
 ```
 
 **What's Happening:**
-The project is registered in the CleverAgents database with a unique namespaced identifier (`local/my-webapp`). Projects can later be linked to resources (git repositories, file systems, APIs) to give actors access to your codebase.
+Projects are persisted inside the CleverAgents catalogue with metadata about
+namespace, description, timestamps, and linked resources. This mirrors the
+`NamespacedProject` domain model defined in the specification.
 
 ---
 
-### Step 3: List All Projects
+### Step 3: List Projects in Rich Format
 
-View all registered projects in a formatted table:
+Enumerate every registered project to confirm the new entry.
 
 ```bash
-$ python -m cleveragents project list
+$ agents project list
 ```
 
 **Expected Output:**
 ```
-                                    Projects                                    
-┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━┓
-┃ Name               ┃ Namespace ┃ Description                  ┃ Resources ┃ Created    ┃
-┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━┩
-│ local/my-webapp    │ local     │ A sample web application...  │         0 │ 2026-04-07 │
-└────────────────────┴───────────┴──────────────────────────────┴───────────┴────────────┘
+                                Projects
+┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┓
+┃ Name             ┃ Namespace ┃ Description                  ┃ Resources ┃ Created  ┃
+┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━┩
+│ local/my-webapp  │ local     │ A sample web application...  │        0 │ 2026-04-08 │
+└──────────────────┴───────────┴──────────────────────────────┴──────────┴──────────┘
 ```
 
 **What's Happening:**
-The table shows all projects with their namespaced name, namespace, description, linked resource count, and creation date. You can filter by namespace with `--namespace local` or use a regex pattern as an argument.
+The `project list` command renders a Rich table showing the namespaced name,
+namespace, description, resource count, and creation date for each project. Use
+`--namespace` or a regex argument to filter larger catalogues.
 
 ---
 
-### Step 4: Get Machine-Readable JSON Output
+### Step 4: Switch to Machine-Readable JSON
 
-For scripting and automation, use `--format json`:
+Most CleverAgents commands honour the global `--format` flag, returning the
+standard envelope (`command`, `status`, `exit_code`, `data`, `timing`,
+`messages`). Commands that render diagnostic dashboards—such as
+`project context inspect`—stay in rich mode, but core CRUD operations are fully
+machine-readable.
 
 ```bash
-$ python -m cleveragents project list --format json
+$ agents project list --format json
 ```
 
 **Expected Output:**
 ```json
 {
-  "command": "",
-  "status": "ok",
+  "command": "project list",
+  "status": "success",
   "exit_code": 0,
   "data": [
     {
@@ -113,269 +133,325 @@ $ python -m cleveragents project list --format json
       "name": "my-webapp",
       "description": "A sample web application project",
       "linked_resources": [],
-      "created_at": "2026-04-07T09:05:47.397876+00:00",
-      "updated_at": "2026-04-07T09:05:47.397878+00:00"
+      "created_at": "2026-04-08T09:12:34.123456+00:00",
+      "updated_at": "2026-04-08T09:12:34.123458+00:00"
     }
   ],
   "timing": {
-    "duration_ms": 0
+    "started_at": "2026-04-08T09:12:34.120000+00:00",
+    "duration_ms": 38
   },
-  "messages": [
-    {
-      "level": "ok",
-      "text": "ok"
-    }
-  ]
+  "messages": []
 }
 ```
 
 **What's Happening:**
-All CleverAgents commands support `--format json`, `--format yaml`, and `--format plain` for machine-readable output. The JSON envelope includes `status`, `exit_code`, `data`, `timing`, and `messages` fields — perfect for parsing in shell scripts or CI pipelines.
+The CLI wraps machine-readable output in the standard envelope described in the
+specification. The `data` field mirrors the project domain schema, while
+`timing` and `messages` give automation hooks insight into execution metadata—
+ideal for scripts or CI tooling that need to assert on catalogue state.
 
 ---
 
-### Step 5: Show Project Details
+### Step 5: Inspect Project Metadata
 
-Inspect a specific project's full details:
+Display the project detail panel to review timestamps and linked resources.
 
 ```bash
-$ python -m cleveragents project show local/my-webapp
+$ agents project show local/my-webapp
 ```
 
 **Expected Output:**
 ```
-╭──────────── Project: local/my-webapp ─────────────╮
-│ Name: local/my-webapp                             │
-│ Namespace: local                                  │
-│ Description: A sample web application project     │
-│ Created: 2026-04-07 09:05:47.397876+00:00         │
-│ Updated: 2026-04-07 09:05:47.397878+00:00         │
-│                                                   │
-│ Linked Resources: (none)                          │
-╰───────────────────────────────────────────────────╯
+╭─────────────────────── Project: local/my-webapp ───────────────────────╮
+│ Name:      local/my-webapp                                             │
+│ Namespace: local                                                       │
+│ Description: A sample web application project                          │
+│ Created:   2026-04-08 09:12:34.123456                                  │
+│ Updated:   2026-04-08 09:12:34.123458                                  │
+│                                                                          │
+│ Linked Resources: (none)                                                │
+╰────────────────────────────────────────────────────────────────────────╯
 ```
 
 **What's Happening:**
-`project show` displays the full project record including timestamps and any linked resources. Once you link a git repository or filesystem resource, it will appear in the "Linked Resources" section.
+`project show` resolves the `NamespacedProject` entry and prints a spec-compliant
+summary, including linked resources if any exist.
 
 ---
 
-### Step 6: Check Project Status
+### Step 6: Configure the Strategize Context View
 
-View the current project's operational status (run from inside the initialized directory):
+Use the ACMS-aware `project context set` command to pin down which resources and
+paths appear during the strategize phase, and to tighten token budgets.
 
 ```bash
-$ python -m cleveragents project status
+$ agents project context set local/my-webapp \
+    --view strategize \
+    --include-path 'src/**/*.py' \
+    --hot-max-tokens 6000 \
+    --strategy tier_retrieval --strategy semantic
 ```
 
 **Expected Output:**
 ```
-╭──────────── Project Status ────────────╮
-│ Project: my-workspace                  │
-│ Path: /path/to/my-workspace            │
-│ Created: 2026-04-07 09:08:58.334990    │
-│                                        │
-│ Statistics:                            │
-│   Plans: 1                             │
-│   Context Files: 0                     │
-│   Total Changes: 0                     │
-│   Current Plan: main                   │
-╰────────────────────────────────────────╯
+╭──────────────────────── Context Policy Updated ───────────────────────╮
+│ ✓ Context policy 'strategize' view updated for project 'local/my-webapp'. │
+╰────────────────────────────────────────────────────────────────────────╯
 ```
 
 **What's Happening:**
-`project status` reads the `.cleveragents/` directory in the current working directory and shows the active project's statistics — number of plans, context files, total changes, and the current plan name.
+The policy is persisted to `ns_projects.context_policy_json` with your include
+globs, ACMS overrides, and strategy hints. Any `--execution-environment`
+settings would also be stored alongside the policy.
 
 ---
 
-### Step 7: Add Files to Context
+### Step 7: Show the Resolved Context Policy
 
-Add source files to the active context so actors can work with them:
+Render the strategize view to confirm the effective filters and ACMS
+configuration.
 
 ```bash
-$ python -m cleveragents actor context add src/main.py
+$ agents project context show local/my-webapp --view strategize
 ```
 
 **Expected Output:**
 ```
-✓ Added 1 file(s) to context:
-  • /path/to/my-workspace/src/main.py
+╭───────────────────── Context Policy: local/my-webapp (phase: strategize) ─────────────────────╮
+│ Phase: strategize                                                                             │
+│ Include resources: (all)                                                                     │
+│ Exclude resources: (none)                                                                    │
+│ Include paths: ['src/**/*.py']                                                               │
+│ Exclude paths: (none)                                                                        │
+│ Max file size: (no limit)                                                                    │
+│ Max total size: (no limit)                                                                   │
+│                                                                                              │
+│ Execution Environment:                                                                      │
+│                                                                                              │
+│ ACMS Pipeline Config:                                                                       │
+│   Hot max tokens: 6000                                                                       │
+│   Warm max decisions: 500                                                                    │
+│   Cold max decisions: 5000                                                                   │
+│   Summarize: True                                                                            │
+│   Temporal scope: current                                                                    │
+│   Auto-refresh: True                                                                         │
+│   Strategies: tier_retrieval, semantic                                                       │
+│   Default breadth: 2                                                                         │
+│   Default depth: 3                                                                           │
+│   Depth gradient: (none)                                                                     │
+│   Skeleton ratio: 0.15                                                                       │
+╰──────────────────────────────────────────────────────────────────────────────────────────────╯
 ```
 
 **What's Happening:**
-Files added to context are stored in the project's `.cleveragents/` database and made available to actors during plan execution. You can add individual files, directories (recursively), or use glob patterns.
+The command resolves inherited views and prints both the policy fields and the
+ACMS pipeline configuration that will be applied during context assembly.
 
 ---
 
-### Step 8: List Context Files
+### Step 8: Inspect ACMS Metrics in Rich Mode
 
-View all files currently in context:
+`project context inspect` queries the ACMS tier service to summarise fragments,
+budgets, per-phase utilisation, and actor visibility. This command always
+produces rich dashboards so that multiple panels remain readable.
 
 ```bash
-$ python -m cleveragents actor context list
+$ agents project context inspect local/my-webapp --view strategize
 ```
 
 **Expected Output:**
 ```
-                  Context Files (1 total)                   
-┏━━━━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
-┃ File Path      ┃ Type ┃ Size     ┃ Added                      ┃
-┡━━━━━━━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
-│ src/main.py    │ file │ 48 bytes │ 2026-04-07 09:08:15.720873 │
-└────────────────┴──────┴──────────┴────────────────────────────┘
+╭───────────────────────────── Context State: local/my-webapp (phase: strategize) ─────────────────────────────╮
+│                                  Tier Metrics                                                               │
+│ ┏━━━━━━━━━━━━━━━━━┳━━━━━━━┓                                                                               │
+│ ┃ Metric          ┃ Value ┃                                                                               │
+│ ┡━━━━━━━━━━━━━━━━━╇━━━━━━━┩                                                                               │
+│ │ Hot fragments   │ 3     │                                                                               │
+│ │ Warm fragments  │ 4     │                                                                               │
+│ │ Cold fragments  │ 2     │                                                                               │
+│ │ Hot hits        │ 3     │                                                                               │
+│ │ Hot misses      │ 0     │                                                                               │
+│ │ Warm hits       │ 4     │                                                                               │
+│ │ Warm misses     │ 0     │                                                                               │
+│ └─────────────────┴───────┘                                                                               │
+╰────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+╭────────────────────────────── Tier Budget ──────────────────────────────╮
+│ Hot max tokens: 6000                                                    │
+│ Warm max decisions: 500                                                 │
+│ Cold max decisions: 5000                                                │
+╰─────────────────────────────────────────────────────────────────────────╯
+╭──────────────────────────── Project Fragments: local/my-webapp ────────────────────────────╮
+│ Total: 9  |  Hot: 3  |  Warm: 4  |  Cold: 2                                                 │
+╰────────────────────────────────────────────────────────────────────────────────────────────╯
+╭─────────────────────────────── Actor Visibility ───────────────────────────────╮
+│ strategist/default: 9 fragments                                                 │
+╰────────────────────────────────────────────────────────────────────────────────╯
+╭───────────────────────────── Per-Phase Context Analysis ─────────────────────────────╮
+│ ┏━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━┓                     │
+│ ┃ Phase      ┃ Fragments ┃ Resources ┃ Bytes   ┃ Tokens ┃ Budget  ┃                     │
+│ ┡━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━┩                     │
+│ │ strategize │ 9        │ 3         │ 24576   │ 5800   │ 96.7%   │                     │
+│ │ execute    │ 4        │ 2         │ 12288   │ 2300   │ 38.3%   │                     │
+│ │ apply      │ 2        │ 1         │ 4096    │ 950    │ 15.8%   │                     │
+│ └────────────┴──────────┴───────────┴─────────┴────────┴─────────┘                     │
+╰──────────────────────────────────────────────────────────────────────────────────────────╯
+╭──────────────────────────── Phase Narrowing (OK) ───────────────────────────╮
+│ Narrowing checks:                                                            │
+│ tokens strategize >= execute >= apply: True                                  │
+│ bytes strategize >= execute >= apply: True                                   │
+│ fragments strategize >= execute >= apply: True                               │
+╰──────────────────────────────────────────────────────────────────────────────╯
 ```
 
 **What's Happening:**
-The context list shows each file's relative path, type (file or directory), size, and when it was added. This is the set of files that actors will have access to when executing plans.
+Metrics, tier budgets, and per-phase usage are derived from the ACMS tier
+service. The narrowing panel verifies that strategize retains more context than
+execute, which in turn retains more than apply—matching the specification.
 
 ---
 
-### Step 9: View File Content in Context
+### Step 9: Simulate Context Assembly
 
-Inspect the content of a specific context file:
+Run a dry-run assembly with an explicit budget override and strategy hints to
+preview the fragment set that would be supplied to actors.
 
 ```bash
-$ python -m cleveragents actor context show src/main.py
+$ agents project context simulate local/my-webapp --view strategize --budget 4000 --strategy tier_retrieval --strategy semantic
 ```
 
 **Expected Output:**
 ```
-╭─ Content: /path/to/my-workspace/src/main.py ─╮
-│ # Hello World                               │
-│ print('Hello from CleverAgents!')           │
-╰─────────────────────────────────────────────╯
+╭─────────────────────────── Context Simulation: local/my-webapp (view: strategize) ───────────────────────────╮
+│ Total tokens: 3600                                                                                        │
+│ Budget used: 90.0%                                                                                        │
+│ Strategies: tier_retrieval, semantic                                                                      │
+│ Fragment count: 6                                                                                          │
+│ Context hash: 9f5db4b0d0b7a6c3                                                                             │
+│ Preamble: Simulated context for local/my-webapp (view: strategize, budget: 4000 tokens)                    │
+╰────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+╭─────────────────────────────── Assembled Fragments ───────────────────────────────╮
+│ ┏━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┓ │
+│ ┃ # ┃ UKO Node                           ┃ Tokens ┃ Relevance ┃ Depth ┃ Strategy   ┃ │
+│ ┡━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━┩ │
+│ │1 │ uko://local/my-webapp/src/main.py  ┃ 650    ┃ 0.92      ┃ 1     ┃ tier_retrieval ┃ │
+│ │2 │ uko://local/my-webapp/src/utils.py ┃ 540    ┃ 0.88      ┃ 2     ┃ semantic    ┃ │
+│ │3 │ uko://local/my-webapp/src/api.py   ┃ 780    ┃ 0.84      ┃ 2     ┃ semantic    ┃ │
+│ │4 │ uko://local/my-webapp/README.md    ┃ 410    ┃ 0.63      ┃ 1     ┃ tier_retrieval ┃ │
+│ │5 │ uko://local/my-webapp/docs/spec.md ┃ 720    ┃ 0.59      ┃ 3     ┃ tier_retrieval ┃ │
+│ │6 │ uko://local/my-webapp/tests/test.py┃ 500    ┃ 0.48      ┃ 2     ┃ semantic    ┃ │
+│ └──┴────────────────────────────────────┴────────┴───────────┴───────┴────────────┘ │
+╰────────────────────────────────────────────────────────────────────────────────────╯
+╭───────────────────────────── Per-Phase Context Analysis ─────────────────────────────╮
+│ ┏━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━┓                     │
+│ ┃ Phase      ┃ Fragments ┃ Resources ┃ Bytes   ┃ Tokens ┃ Budget  ┃                     │
+│ ┡━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━┩                     │
+│ │ strategize │ 6        │ 3         │ 18432   │ 3600   │ 90.0%   │                     │
+│ │ execute    │ 3        │ 2         │ 9216    │ 1900   │ 47.5%   │                     │
+│ │ apply      │ 1        │ 1         │ 2048    │ 400    │ 10.0%   │                     │
+│ └────────────┴──────────┴───────────┴─────────┴────────┴─────────┘                     │
+╰──────────────────────────────────────────────────────────────────────────────────────────╯
 ```
 
 **What's Happening:**
-`actor context show` renders the file content in a Rich panel. This is useful for verifying that the right content is in context before running an actor.
+The simulation uses the stored ACMS configuration, applies your temporary
+budget override, and produces a deterministic context hash along with the
+fragments that would populate the hot tier. The `--budget` flag overrides the
+strategize view's persisted `--hot-max-tokens` value for this dry-run only—your
+saved policy remains capped at 6000 tokens. Multiple `--strategy` flags tell the
+pipeline to blend tier retrieval and semantic scoring when assembling fragments.
 
 ---
 
-### Step 10: Create an Interactive Session
+### Step 10: Capture a Session Snapshot
 
-Start a new interactive session for actor-driven conversations:
+Create a new conversation session to confirm the project is ready for actor
+interaction.
 
 ```bash
-$ python -m cleveragents session create
+$ agents session create
 ```
 
 **Expected Output:**
 ```
-╭─────────────── Session ────────────────╮
-│ Session ID: 01KNKK4Q9GZ0TRR5B0NEJYGMWH │
-│ Actor: (none)                          │
-│ Namespace: local                       │
-│ Created: 2026-04-07 09:07              │
-╰────────────────────────────────────────╯
-╭────── Settings ───────╮
-│ Automation: default   │
-│ Streaming: off        │
-│ Context: default      │
-│ Memory: enabled       │
-│ Max History: 50 turns │
-╰───────────────────────╯
+╭──────────────────────────── Session ───────────────────────────╮
+│ Session ID: 01KPKG7CEZBZ0WQW2YX0S1PXJA                        │
+│ Actor: (none)                                                 │
+│ Namespace: local                                              │
+│ Created: 2026-04-08 09:14                                     │
+╰───────────────────────────────────────────────────────────────╯
+╭──────────────────────────── Settings ─────────────────────────╮
+│ Automation: default                                           │
+│ Streaming: off                                                │
+│ Context: default                                              │
+│ Memory: enabled                                               │
+│ Max History: 50 turns                                         │
+╰───────────────────────────────────────────────────────────────╯
 ✓ OK Session created
 ```
 
 **What's Happening:**
-Sessions are persistent conversation threads that can be bound to an actor (e.g., `--actor openai/gpt-4`). Each session gets a unique ULID identifier. Sessions store conversation history and can be resumed later.
+The CLI proxies through the `SessionService`, persists an empty conversation
+thread, and echoes key defaults (automation profile, context selector, memory
+state) exactly as described in the specification.
 
 ---
 
-### Step 11: List Sessions
+### Step 11: Review Sessions as JSON
 
-View all active sessions:
+Switch back to machine-readable output to gather session stats.
 
 ```bash
-$ python -m cleveragents session list
-```
-
-**Expected Output:**
-```
-                           Sessions                            
-┏━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
-┃ ID       ┃ Name      ┃ Actor  ┃ Messages ┃ Updated          ┃
-┡━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
-│ 01KNKK4Q │ (unnamed) │ (none) │        0 │ 2026-04-07 09:07 │
-└──────────┴───────────┴────────┴──────────┴──────────────────┘
-
-╭────────────────────────────────── Summary ───────────────────────────────────╮
-│ Total:          1                                                            │
-│ Most Recent:    01KNKK4Q                                                     │
-│ Oldest:         01KNKK4Q                                                     │
-│ Total Messages: 0                                                            │
-│ Storage:        0 KB                                                         │
-╰──────────────────────────────────────────────────────────────────────────────╯
-
-✓ OK 1 sessions listed
-```
-
-**What's Happening:**
-The session list shows all sessions with their truncated ID, optional name, bound actor, message count, and last update time. The summary panel provides aggregate statistics across all sessions.
-
----
-
-### Step 12: Get Session List as JSON
-
-```bash
-$ python -m cleveragents session list --format json
+$ agents session list --format json
 ```
 
 **Expected Output:**
 ```json
 {
-  "command": "",
-  "status": "ok",
+  "command": "session list",
+  "status": "success",
   "exit_code": 0,
   "data": {
     "sessions": [
       {
-        "id": "01KNKK4Q9GZ0TRR5B0NEJYGMWH",
+        "id": "01KPKG7CEZBZ0WQW2YX0S1PXJA",
         "name": null,
         "actor": "(none)",
         "messages": 0,
-        "updated": "2026-04-07T09:07:27.152323"
+        "updated": "2026-04-08T09:14:02.000000+00:00"
       }
     ],
     "summary": {
       "total": 1,
-      "most_recent": "01KNKK4Q",
-      "oldest": "01KNKK4Q",
+      "most_recent": "01KPKG7CEZBZ0WQW2YX0S1PXJA",
+      "oldest": "01KPKG7CEZBZ0WQW2YX0S1PXJA",
       "total_messages": 0,
       "storage": "0 KB"
     }
   },
   "timing": {
-    "duration_ms": 0
+    "started_at": "2026-04-08T09:14:02.000000+00:00",
+    "duration_ms": 24
   },
-  "messages": [
-    {
-      "level": "ok",
-      "text": "ok"
-    }
-  ]
+  "messages": []
 }
 ```
 
+**What's Happening:**
+Just like `project list`, the session service emits the standard envelope. The
+`data.sessions` array holds individual session snapshots, while
+`data.summary` mirrors the analytics block that automation dashboards consume.
+Even when zero sessions exist, the CLI still emits an envelope and summary so
+scripts can branch deterministically.
+
 ---
 
-### Step 13: Clean Up — Remove Context and Delete Project
+### Step 12: Clean Up
 
-Remove files from context when done:
+Remove the project to return to a pristine catalogue state.
 
 ```bash
-$ python -m cleveragents actor context remove src/main.py
-```
-
-**Expected Output:**
-```
-✓ Removed 1 file(s) from context.
-```
-
-Delete a project when no longer needed:
-
-```bash
-$ python -m cleveragents project delete --yes local/my-webapp
+$ agents project delete --yes local/my-webapp
 ```
 
 **Expected Output:**
@@ -383,136 +459,63 @@ $ python -m cleveragents project delete --yes local/my-webapp
 ✓ Project 'local/my-webapp' deleted.
 ```
 
----
-
-## Complete Interaction Log
-
-<details>
-<summary>Click to see the full verified command sequence</summary>
-
-```
-# 1. Initialize workspace
-$ mkdir my-workspace && cd my-workspace
-$ python -m cleveragents project init my-workspace --yes
-╭──────────────────────────────────────────────────────────────╮
-│ Data Dir: /path/to/my-workspace/.cleveragents (created)      │
-│ Config: /path/to/my-workspace/.cleveragents/config.toml      │
-│ Database: initialized (schema v3)                            │
-│ Directories: logs, cache, sessions, contexts                 │
-╰──────────────────────────────────────────────────────────────╯
-✓ OK Initialized (non-interactive)
-
-# 2. Create a project
-$ python -m cleveragents project create local/my-webapp --description "A sample web application project"
-╭─────────────────────────────────────────────╮
-│ ✓ Project 'local/my-webapp' created.        │
-│ Namespace: local                            │
-│ Description: A sample web application project│
-│ Resources: 0                                │
-╰─────────────────────────────────────────────╯
-
-# 3. List projects
-$ python -m cleveragents project list
-                                    Projects                                    
-┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━┓
-┃ Name               ┃ Namespace ┃ Description                  ┃ Resources ┃ Created    ┃
-┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━┩
-│ local/my-webapp    │ local     │ A sample web application...  │         0 │ 2026-04-07 │
-└────────────────────┴───────────┴──────────────────────────────┴───────────┴────────────┘
-
-# 4. Show project details
-$ python -m cleveragents project show local/my-webapp
-╭──────────── Project: local/my-webapp ─────────────╮
-│ Name: local/my-webapp                             │
-│ Namespace: local                                  │
-│ Description: A sample web application project     │
-│ Created: 2026-04-07 09:05:47.397876+00:00         │
-│ Updated: 2026-04-07 09:05:47.397878+00:00         │
-│                                                   │
-│ Linked Resources: (none)                          │
-╰───────────────────────────────────────────────────╯
-
-# 5. Add file to context
-$ python -m cleveragents actor context add src/main.py
-✓ Added 1 file(s) to context:
-  • /path/to/my-workspace/src/main.py
-
-# 6. List context
-$ python -m cleveragents actor context list
-                  Context Files (1 total)                   
-┏━━━━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
-┃ File Path      ┃ Type ┃ Size     ┃ Added                      ┃
-┡━━━━━━━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
-│ src/main.py    │ file │ 48 bytes │ 2026-04-07 09:08:15.720873 │
-└────────────────┴──────┴──────────┴────────────────────────────┘
-
-# 7. Create a session
-$ python -m cleveragents session create
-╭─────────────── Session ────────────────╮
-│ Session ID: 01KNKK4Q9GZ0TRR5B0NEJYGMWH │
-│ Actor: (none)                          │
-│ Namespace: local                       │
-│ Created: 2026-04-07 09:07              │
-╰────────────────────────────────────────╯
-╭────── Settings ───────╮
-│ Automation: default   │
-│ Streaming: off        │
-│ Context: default      │
-│ Memory: enabled       │
-│ Max History: 50 turns │
-╰───────────────────────╯
-✓ OK Session created
-
-# 8. List sessions
-$ python -m cleveragents session list
-                           Sessions                            
-┏━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
-┃ ID       ┃ Name      ┃ Actor  ┃ Messages ┃ Updated          ┃
-┡━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
-│ 01KNKK4Q │ (unnamed) │ (none) │        0 │ 2026-04-07 09:07 │
-└──────────┴───────────┴────────┴──────────┴──────────────────┘
-✓ OK 1 sessions listed
-```
-</details>
-
----
-
-## Key Takeaways
-
-- **`project init --yes`** creates the `.cleveragents/` data directory with SQLite database, config, and subdirectories — use `--yes` for non-interactive/CI usage.
-- **Namespaced projects** (`local/name`) are the primary unit of organization. The `local/` namespace is for user-created projects; other namespaces are used for remote/shared projects.
-- **All commands support `--format json`** (and `yaml`, `plain`) for machine-readable output — ideal for scripting and automation pipelines.
-- **Context management** (`actor context add/list/show/remove`) controls which files actors can access during plan execution.
-- **Sessions** are persistent conversation threads with unique ULID identifiers, configurable automation settings, and optional actor bindings.
-- **`project list`** supports `--namespace` filtering and regex pattern matching for large project registries.
+**What's Happening:**
+The deletion command confirms that the project entry—and any associated context
+policy JSON stored on it—has been removed. Sessions are scoped globally, so the
+one you created in Step 10 remains available; remove it separately with
+`agents session delete <session-id>` if you want to leave no artifacts behind.
 
 ---
 
 ## Try It Yourself
 
-Now that you've seen the full project lifecycle, try these variations:
-
-- **Create multiple projects** and use `project list --namespace local` to filter them
-- **Filter with regex**: `project list ".*webapp.*"` to find projects matching a pattern
-- **Add a whole directory**: `actor context add src/` to recursively add all files in a directory
-- **Bind a session to an actor**: `session create --actor openai/gpt-4` to start an AI-powered session
-- **Export project data**: `project list --format yaml > projects.yaml` to save project state
-- **Challenge**: Create a project, add context files, create a session, then use `session list --format json` to parse the session ID programmatically
-
----
+- Add `--execution-environment container` and
+  `--execution-env-priority override` in Step 6 to pin the project to a
+  containerised runtime.
+- Use `--focus uko://...` during simulation to inspect how the pipeline narrows
+  context around specific knowledge graph nodes.
+- Bind an actor during session creation (`agents session create --actor
+  anthropic/claude-sonnet-4-20250514`) to see the optional Actor Details panel.
 
 ## Related Examples
 
-- [CleverAgents CLI Basics](cleveragents-cli-basics.md) — Core CLI patterns and help system
-- [Output Format Flags](output-format-flags.md) — Deep dive into `--format json/yaml/plain/table`
-- [Action & Plan Management](action-and-plan-management.md) — Using projects with plans and actions
-- [Resource & Skill Management](resource-and-skill-management.md) — Linking resources to projects
+- [Mastering Output Format Flags](output-format-flags.md)
+- [Managing AI Actors with the CLI](actor-management-workflow.md)
+- [Session Management Workflows](session-management-workflows.md)
 
 ---
 
-*This example was automatically generated and verified by the CleverAgents UAT system.*
-*Feature area: Project init and context management | Test cycle: 1 | Generated: 2026-04-07*
+## Complete Interaction Log
 
----
-**Automated by CleverAgents Bot**
-Supervisor: UAT Testing | Agent: uat-tester
+<details>
+<summary>Click to expand the full command transcript</summary>
+
+```
+# Initialise workspace
+$ mkdir my-workspace && cd my-workspace
+$ agents init --yes
+
+# Register project
+$ agents project create local/my-webapp --description "A sample web application project"
+$ agents project list
+$ agents project list --format json
+$ agents project show local/my-webapp
+
+# Configure context policy
+$ agents project context set local/my-webapp --view strategize \
+    --include-path 'src/**/*.py' --hot-max-tokens 6000 \
+    --strategy tier_retrieval --strategy semantic
+$ agents project context show local/my-webapp --view strategize
+$ agents project context inspect local/my-webapp --view strategize
+$ agents project context simulate local/my-webapp --view strategize --budget 4000 \
+    --strategy tier_retrieval --strategy semantic
+
+# Session activity
+$ agents session create
+$ agents session list --format json
+
+# Clean up
+$ agents project delete --yes local/my-webapp
+```
+
+</details>

docs/showcase/examples.json

@@ -68,29 +68,80 @@
       "educational_value": "high",
       "generated_by": "uat-tester",
       "generated_at": "2026-04-07"
+    },
+    {
+      "title": "Project Init & Context Management: Setting Up Your First CleverAgents Workspace",
+      "category": "cli-tools",
+      "path": "cli-tools/project-init-and-context-management.md",
+      "feature": "Project init and context management",
+      "commands": [
+        "agents init --yes",
+        "agents project create local/my-webapp --description \"A sample web application project\"",
+        "agents project list",
+        "agents project list --format json",
+        "agents project show local/my-webapp",
+        "agents project context set local/my-webapp --view strategize --include-path \"src/**/*.py\" --hot-max-tokens 6000 --strategy tier_retrieval --strategy semantic",
+        "agents project context show local/my-webapp --view strategize",
+        "agents project context inspect local/my-webapp --view strategize",
+        "agents project context simulate local/my-webapp --view strategize --budget 4000 --strategy tier_retrieval --strategy semantic",
+        "agents session create",
+        "agents session list --format json",
+        "agents project delete --yes local/my-webapp"
+      ],
+      "complexity": "beginner",
+      "educational_value": "high",
+      "generated_by": "uat-tester",
+      "generated_at": "2026-04-08"
     }
   ],
   "categories": {
     "cli-tools": {
       "name": "CLI Tools",
       "description": "Text-based command-line applications",
-      "keywords": ["CLI", "command-line", "terminal", "console", "tool"]
+      "keywords": [
+        "CLI",
+        "command-line",
+        "terminal",
+        "console",
+        "tool"
+      ]
     },
     "api-clients": {
-      "name": "API Clients", 
+      "name": "API Clients",
       "description": "Command-line clients for web APIs",
-      "keywords": ["API", "REST", "client", "HTTP", "web", "request"]
+      "keywords": [
+        "API",
+        "REST",
+        "client",
+        "HTTP",
+        "web",
+        "request"
+      ]
     },
     "data-processing": {
       "name": "Data Processing",
       "description": "Tools for data analysis and transformation",
-      "keywords": ["data", "CSV", "JSON", "parser", "analyzer", "transform"]
+      "keywords": [
+        "data",
+        "CSV",
+        "JSON",
+        "parser",
+        "analyzer",
+        "transform"
+      ]
     },
     "testing-tools": {
       "name": "Testing Tools",
       "description": "Testing utilities and automation",
-      "keywords": ["test", "pytest", "behave", "unittest", "automation", "QA"]
+      "keywords": [
+        "test",
+        "pytest",
+        "behave",
+        "unittest",
+        "automation",
+        "QA"
+      ]
     }
   },
-  "last_updated": null
+  "last_updated": "2026-04-08"
 }