@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.3

package/apps/cad-creator/shared/cad/src/types.ts

@@ -0,0 +1,507 @@
+export type MeasurementUnit = 'in' | 'ft' | 'm' | 'mm';
+
+export type WallMaterial = 'drywall' | 'brick' | 'concrete' | 'glass' | 'wood_panel' | 'steel';
+
+export type FloorMaterial = 'hardwood' | 'marble' | 'tile' | 'polished_concrete' | 'carpet' | 'terrazzo';
+
+export interface WallElement {
+  id: string;
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
+  thickness: number; // in inches (e.g. 6)
+  height3D: number; // in inches (e.g. 96 or 108)
+  material: WallMaterial;
+  color?: string;
+  exterior?: boolean;
+  sourceSketchShapeIds?: string[];
+}
+
+export interface DoorElement {
+  id: string;
+  wallId: string;
+  distanceAlongWall: number; // 0 to 1 ratio or absolute offset
+  width: number; // in inches (e.g. 36)
+  height: number; // in inches (e.g. 84)
+  swing: 'left' | 'right' | 'sliding' | 'double' | 'pocket';
+  openAngle: number; // 0 to 90 degrees
+  label?: string;
+  sourceSketchShapeIds?: string[];
+}
+
+export interface WindowElement {
+  id: string;
+  wallId: string;
+  distanceAlongWall: number; // 0 to 1 ratio
+  width: number; // in inches (e.g. 48)
+  height: number; // in inches (e.g. 60)
+  elevation: number; // height from floor in inches (e.g. 36)
+  style: 'casement' | 'sliding' | 'picture' | 'hung';
+  label?: string;
+  sourceSketchShapeIds?: string[];
+}
+
+export type FurnitureCategory = 'seating' | 'tables' | 'bedroom' | 'kitchen' | 'bathroom' | 'office' | 'decor' | 'parametric';
+
+export interface FurnitureElement {
+  id: string;
+  type: string; // 'sofa_3seater', 'king_bed', 'dining_table_6', 'desk', 'kitchen_island', 'toilet', 'bathtub', 'potted_plant', etc.
+  category: FurnitureCategory;
+  name: string;
+  x: number; // center x in inches
+  y: number; // center y in inches
+  w: number; // width in inches
+  d: number; // depth in inches
+  h: number; // height in inches
+  rotation: number; // in degrees
+  color: string;
+  material?: string;
+  icon?: string;
+  parametricObjectId?: string;
+  sourceSketchShapeIds?: string[];
+}
+
+export interface RoomZone {
+  id: string;
+  name: string;
+  points: [number, number][]; // Polygon vertices in inches
+  areaSqFt: number;
+  floorMaterial: FloorMaterial;
+  color: string;
+  sourceSketchShapeIds?: string[];
+}
+
+export interface DimensionAnnotation {
+  id: string;
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
+  label: string;
+  sourceSketchShapeIds?: string[];
+}
+
+export interface LightingConfig {
+  sunAltitude: number; // 10 to 90 degrees
+  sunAzimuth: number; // 0 to 360 degrees
+  intensity: number; // 0.2 to 2.0
+  timeOfDay: 'morning' | 'noon' | 'sunset' | 'night';
+  shadows: boolean;
+  ambientColor: string;
+}
+
+// ---------------------------------------------------------------------------
+// PARAMETRIC & OPENSCAD DOMAIN MODEL
+// ---------------------------------------------------------------------------
+
+export type ParametricGeneratorType = 'openscad' | 'procedural_csg' | 'custom_script';
+
+export interface ParametricParameterDef {
+  name: string;
+  label: string;
+  type: 'number' | 'string' | 'boolean' | 'select';
+  value: number | string | boolean;
+  min?: number;
+  max?: number;
+  step?: number;
+  unit?: string;
+  options?: { label: string; value: string | number }[];
+  description?: string;
+}
+
+export interface ParametricObject {
+  id: string;
+  name: string;
+  generator: ParametricGeneratorType;
+  generatorTemplate?: string; // 'workstation' | 'bookshelf' | 'chair' | 'pergola' | 'cabinet' | 'custom'
+  parameters: Record<string, number | string | boolean>;
+  parameterDefs?: ParametricParameterDef[];
+  transform: {
+    x: number; // in inches
+    y: number; // in inches (floor plane)
+    z: number; // elevation in inches
+    rotationX?: number;
+    rotationY?: number; // rotation around Y axis in degrees
+    rotationZ?: number;
+  };
+  source: string; // OpenSCAD source code (.scad)
+  generatedArtifacts?: DesignArtifactSummary[];
+  updatedAt?: number;
+}
+
+export interface DesignArtifactSummary {
+  id: string;
+  format: 'stl' | '3mf' | 'dxf' | 'scad' | 'obj' | 'svg' | 'json';
+  filename: string;
+  sizeBytes: number;
+  createdAt: number;
+  checksum?: string;
+}
+
+// ---------------------------------------------------------------------------
+// CANONICAL PROJECT STATE & METADATA
+// ---------------------------------------------------------------------------
+
+export interface ProjectMetadata {
+  author?: string;
+  description?: string;
+  tags?: string[];
+  createdAt: number;
+  updatedAt: number;
+  revision: number;
+  revisionMessage?: string;
+}
+
+export interface ProjectLayer {
+  id: string;
+  name: string;
+  visible: boolean;
+  locked: boolean;
+  color?: string;
+}
+
+export interface SketchDocumentRef {
+  tldrawSnapshot?: any; // Serialized tldraw store snapshot
+  shapesCount?: number;
+  lastEditedAt?: number;
+}
+
+export interface DesignProject {
+  id: string;
+  name: string;
+  units?: MeasurementUnit;
+  scale: number; // 1 canvas unit = 1 inch
+  gridSize: number; // grid step in inches (default 12 inches = 1 ft)
+  snapToGrid: boolean;
+  layers?: ProjectLayer[];
+  walls: WallElement[];
+  doors: DoorElement[];
+  windows: WindowElement[];
+  furniture: FurnitureElement[];
+  rooms: RoomZone[];
+  annotations: DimensionAnnotation[];
+  parametricObjects?: ParametricObject[];
+  sketchDocument?: SketchDocumentRef;
+  lighting: LightingConfig;
+  roofType: 'none' | 'flat' | 'gable';
+  ceilingHeight: number; // e.g. 108 inches
+  metadata?: ProjectMetadata;
+  updatedAt: number;
+  version: number;
+}
+
+// Backwards-compatible alias
+export type ProjectState = DesignProject;
+
+// ---------------------------------------------------------------------------
+// CANONICAL DESIGN OPERATIONS (COMMANDS)
+// ---------------------------------------------------------------------------
+
+export type DesignOperationType =
+  | 'create_wall'
+  | 'update_wall'
+  | 'delete_wall'
+  | 'create_room'
+  | 'update_room'
+  | 'delete_room'
+  | 'add_door'
+  | 'update_door'
+  | 'delete_door'
+  | 'add_window'
+  | 'update_window'
+  | 'delete_window'
+  | 'add_fixture'
+  | 'update_fixture'
+  | 'delete_fixture'
+  | 'move_element'
+  | 'create_parametric_object'
+  | 'update_parametric_parameter'
+  | 'update_parametric_source'
+  | 'delete_parametric_object'
+  | 'attach_sketch'
+  | 'convert_sketch_selection'
+  | 'set_material'
+  | 'set_lighting'
+  | 'batch_operations';
+
+export interface BaseDesignOperation {
+  id: string;
+  type: DesignOperationType;
+  timestamp: number;
+  authorId?: string;
+}
+
+export interface CreateWallOp extends BaseDesignOperation {
+  type: 'create_wall';
+  wall: WallElement;
+}
+
+export interface UpdateWallOp extends BaseDesignOperation {
+  type: 'update_wall';
+  wallId: string;
+  updates: Partial<WallElement>;
+}
+
+export interface DeleteWallOp extends BaseDesignOperation {
+  type: 'delete_wall';
+  wallId: string;
+}
+
+export interface CreateRoomOp extends BaseDesignOperation {
+  type: 'create_room';
+  room: RoomZone;
+}
+
+export interface UpdateRoomOp extends BaseDesignOperation {
+  type: 'update_room';
+  roomId: string;
+  updates: Partial<RoomZone>;
+}
+
+export interface DeleteRoomOp extends BaseDesignOperation {
+  type: 'delete_room';
+  roomId: string;
+}
+
+export interface AddDoorOp extends BaseDesignOperation {
+  type: 'add_door';
+  door: DoorElement;
+}
+
+export interface UpdateDoorOp extends BaseDesignOperation {
+  type: 'update_door';
+  doorId: string;
+  updates: Partial<DoorElement>;
+}
+
+export interface DeleteDoorOp extends BaseDesignOperation {
+  type: 'delete_door';
+  doorId: string;
+}
+
+export interface AddWindowOp extends BaseDesignOperation {
+  type: 'add_window';
+  window: WindowElement;
+}
+
+export interface UpdateWindowOp extends BaseDesignOperation {
+  type: 'update_window';
+  windowId: string;
+  updates: Partial<WindowElement>;
+}
+
+export interface DeleteWindowOp extends BaseDesignOperation {
+  type: 'delete_window';
+  windowId: string;
+}
+
+export interface AddFixtureOp extends BaseDesignOperation {
+  type: 'add_fixture';
+  fixture: FurnitureElement;
+}
+
+export interface UpdateFixtureOp extends BaseDesignOperation {
+  type: 'update_fixture';
+  fixtureId: string;
+  updates: Partial<FurnitureElement>;
+}
+
+export interface DeleteFixtureOp extends BaseDesignOperation {
+  type: 'delete_fixture';
+  fixtureId: string;
+}
+
+export interface MoveElementOp extends BaseDesignOperation {
+  type: 'move_element';
+  elementType: 'wall' | 'door' | 'window' | 'furniture' | 'room' | 'parametric';
+  elementId: string;
+  dx: number;
+  dy: number;
+  dz?: number;
+}
+
+export interface CreateParametricObjectOp extends BaseDesignOperation {
+  type: 'create_parametric_object';
+  parametricObject: ParametricObject;
+}
+
+export interface UpdateParametricParameterOp extends BaseDesignOperation {
+  type: 'update_parametric_parameter';
+  parametricObjectId: string;
+  parameterName: string;
+  value: number | string | boolean;
+}
+
+export interface UpdateParametricSourceOp extends BaseDesignOperation {
+  type: 'update_parametric_source';
+  parametricObjectId: string;
+  source: string;
+}
+
+export interface DeleteParametricObjectOp extends BaseDesignOperation {
+  type: 'delete_parametric_object';
+  parametricObjectId: string;
+}
+
+export interface AttachSketchOp extends BaseDesignOperation {
+  type: 'attach_sketch';
+  sketchDocument: SketchDocumentRef;
+}
+
+export interface ConvertSketchSelectionOp extends BaseDesignOperation {
+  type: 'convert_sketch_selection';
+  sourceShapeIds: string[];
+  proposedOperations: DesignOperation[];
+}
+
+export interface SetLightingOp extends BaseDesignOperation {
+  type: 'set_lighting';
+  lighting: Partial<LightingConfig>;
+}
+
+export interface BatchOperationsOp extends BaseDesignOperation {
+  type: 'batch_operations';
+  operations: DesignOperation[];
+}
+
+export type DesignOperation =
+  | CreateWallOp
+  | UpdateWallOp
+  | DeleteWallOp
+  | CreateRoomOp
+  | UpdateRoomOp
+  | DeleteRoomOp
+  | AddDoorOp
+  | UpdateDoorOp
+  | DeleteDoorOp
+  | AddWindowOp
+  | UpdateWindowOp
+  | DeleteWindowOp
+  | AddFixtureOp
+  | UpdateFixtureOp
+  | DeleteFixtureOp
+  | MoveElementOp
+  | CreateParametricObjectOp
+  | UpdateParametricParameterOp
+  | UpdateParametricSourceOp
+  | DeleteParametricObjectOp
+  | AttachSketchOp
+  | ConvertSketchSelectionOp
+  | SetLightingOp
+  | BatchOperationsOp;
+
+// ---------------------------------------------------------------------------
+// ARTIFACT EXPORTER & PUBLISHER MODELS
+// ---------------------------------------------------------------------------
+
+export type ExportFormat = 'json' | 'svg' | 'dxf' | 'obj' | 'scad' | 'stl' | '3mf' | 'gltf';
+
+export interface DesignArtifact {
+  id: string;
+  projectId: string;
+  revisionId: string;
+  format: ExportFormat;
+  mimeType: string;
+  filename: string;
+  size: number;
+  createdAt: number;
+  generator: string;
+  checksum: string;
+  content: string | Uint8Array;
+  localUrl?: string;
+  storageRef?: string;
+  metadata?: Record<string, any>;
+}
+
+export type PublisherDestinationId = 'local' | 'github' | 'cloudflare' | 'docker' | 'custom';
+
+export interface PublisherCapabilities {
+  supportsPrivatePublish: boolean;
+  supportsReleases: boolean;
+  supportsDirectArtifacts: boolean;
+  requiresAuthToken: boolean;
+  authFields?: { key: string; label: string; type: 'text' | 'password'; placeholder?: string; required?: boolean }[];
+}
+
+export interface PublishResult {
+  success: boolean;
+  destination: PublisherDestinationId;
+  targetUrl?: string;
+  receiptId: string;
+  publishedAt: number;
+  filesCount: number;
+  message: string;
+  metadata?: Record<string, any>;
+}
+
+export interface ProjectRevisionReceipt {
+  revisionId: string;
+  projectId: string;
+  revisionNumber: number;
+  timestamp: number;
+  message: string;
+  author?: string;
+  wallsCount: number;
+  roomsCount: number;
+  parametricCount: number;
+}
+
+// ---------------------------------------------------------------------------
+// MULTIPLAYER, ROLES, AND STUDIO UI STATE
+// ---------------------------------------------------------------------------
+
+export type UserRole = 'Owner' | 'Editor' | 'Viewer';
+
+export interface RolePermissions {
+  canEditGeometry: boolean;
+  canUseAIAssistant: boolean;
+  canUploadSketches: boolean;
+  canChangeSettings: boolean;
+  canManageRoles: boolean;
+  canLoadTemplates: boolean;
+  canSaveRevisions: boolean;
+  canExport: boolean;
+  canGenerateMedia: boolean;
+  canEditParametric: boolean;
+}
+
+export interface MultiplayerUser {
+  id: string;
+  name: string;
+  color: string;
+  role: UserRole;
+  cursor?: { x: number; y: number; view: '2d' | '3d' };
+  selectedIds: string[];
+  activeTool: string;
+  lastActive: number;
+}
+
+export interface ChatMessage {
+  id: string;
+  role: 'user' | 'agent' | 'system';
+  text: string;
+  timestamp: number;
+  planData?: Partial<DesignProject>;
+  suggestedPrompts?: string[];
+  generatedImages?: { url: string; prompt: string; timestamp: number }[];
+  videoResult?: { url: string; prompt: string; operationName?: string };
+  isStreaming?: boolean;
+}
+
+export type ActiveTool =
+  | 'select'
+  | 'wall'
+  | 'door'
+  | 'window'
+  | 'room'
+  | 'furniture'
+  | 'dimension'
+  | 'measure'
+  | 'eraser'
+  | 'pan';
+
+export type StudioTabMode = 'plan' | 'sketch' | '3d' | 'parametric' | 'render';
+
+export type ViewMode = 'split' | '2d' | '3d' | 'firstperson' | 'sketch' | 'parametric' | 'robotics';
+

package/apps/cad-creator/shared/cad/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": [
+    "src"
+  ]
+}

package/docs/AUTORAG.md

@@ -0,0 +1,58 @@
+# AgentSam AutoRAG
+
+AutoRAG is the setup and orchestration layer for the existing AgentSam knowledge engine. It discovers a repository, selects a deliberately bounded corpus/lane, records a portable profile in `.agentsam/knowledge.json`, and verifies that profile with a safe probe. It is not a second indexer, a giant company collection, or a credentials store.
+
+## Local quickstart
+
+```bash
+agentsam autorag setup
+agentsam autorag probe
+agentsam index plan
+agentsam index run
+agentsam search "the symbol or phrase"
+```
+
+The default is local SQLite, structural and lexical retrieval, and no embedding request. Docker, Cloudflare, Supabase, a company graph, and a paid provider are all optional.
+
+For a non-interactive code profile:
+
+```bash
+agentsam autorag setup --yes --kind code --scope packages,src
+```
+
+For documents, choose literal paths rather than embedding a whole checkout by default:
+
+```bash
+agentsam autorag setup --yes --kind documents --scope docs,README.md
+```
+
+`setup` and `configure` write only `.agentsam/knowledge.json`; they never serialize API keys. Provider credentials resolve from the environment, an authenticated host/vault, or an installed provider connector.
+
+## Providers and backends
+
+`agentsam autorag providers` reports the actual registry. Gemini, OpenAI, Workers AI, Ollama, and deterministic `fixture` adapters share the same embedding contract. An unavailable credential/binding is reported unavailable and fails closed; changing a model string never changes another provider's transport.
+
+`agentsam autorag backends` reports `local_exact`, `postgres_pgvector`, `supabase_pgvector`, and `cloudflare_vectorize`. A nonlocal backend requires an explicit resource; Vectorize additionally requires an explicit binding and index. A lane's provider/model/dimensions/backend/resource combination is explicit, so incompatible vector dimensions cannot silently share a physical index.
+
+Use semantic embeddings deliberately. A normal local setup makes none. A probe refuses paid semantic work unless explicitly enabled:
+
+```bash
+agentsam autorag configure --yes --provider fixture --semantic --dimensions 3
+agentsam autorag probe --semantic
+```
+
+## Probe and evidence
+
+`agentsam autorag probe` limits itself to 25 files, 100 chunks, and one query. It creates a dedicated probe generation, so a failed probe cannot replace the active non-probe generation. Its receipt records scope, profile, backend, Git evidence, Merkle root, counts, and the bounded query result.
+
+For code, planning is structural-first: symbol/path lexical matching and JS/TS AST observations remain primary; semantic vectors supplement them. The engine consumes the repository package's deterministic content Merkle and semantic metadata root. Merkle answers what exact filesystem evidence changed; it does not replace AST/import graphs, repository contracts, dependencies, or retrieval generations.
+
+## Company graph and Docker
+
+A host may supply a company-graph adapter. It classifies intent, chooses candidate repositories through contracts/dependencies, resolves repository-specific lanes, then merges bounded evidence. It does not search every repository or create one company-wide vector collection. Repository-specific intent routes override account routes, which override portable defaults.
+
+`agentsam dockerize --type knowledge_service` remains an optional execution host around the same engine. Normal local setup never starts or requires Docker.
+
+## Troubleshooting
+
+Run `agentsam autorag doctor` for config, Git/Merkle, local store, and selected-provider status. Run `agentsam autorag status` to inspect discovery/config, and `agentsam autorag lanes` to see the configured explicit lane. A provider marked unavailable is a capability result, not a reason to add a secret to project config.

package/docs/BRAND_INTELLIGENCE.md

@@ -0,0 +1,30 @@
+# Brand Intelligence + Interactive CLI (implementation status)
+
+**Repo:** `agentsam-sdk` · **Date:** 2026-09-24
+
+| Item | Status | Evidence |
+|------|--------|----------|
+| 1. Architecture inspected | implemented | repository.snapshot + security shared authority pattern |
+| 2. Reusable machinery identified | implemented | merkle/gitignore via snapshot |
+| 3. Capability contracts | implemented | `protocol/capabilities/manifest.json` brand.* |
+| 4. Brand scanner | implemented | `packages/agentsam-brand/src/scan.js` |
+| 5. Brand resolver | implemented | `packages/agentsam-brand/src/resolve.js` |
+| 6. Brand Contract draft | implemented | `buildBrandContractDraft` + `.agentsam/brand/` |
+| 7. Progression engine | implemented | `src/progression/engine.js` (generic) |
+| 8. Deterministic conversational router | partial | `routeDeterministicIntent`; shell wiring thin |
+| 9. Interactive session state | partial | existing sessions; brand not fully session-bound |
+| 10. TUI event model | partial | brand.scan emits operation.* events → runtime-activity |
+| 11. TUI views | partial | activity panel during scan; full shell mockup not rebuilt |
+| 12. No-model experience | implemented | tests + CLI without model |
+| 13. Model-assisted | not applicable yet | brand.plan marked model_assisted_optional |
+| 14. GOAP integration | partial | `--goap` greedy sequencer + action catalog |
+| 15. Receipts | partial | `receipt` + `next_actions` on scan/plan |
+| 16. Presets | implemented | cms → cms,knowledge,brand,theme |
+| 17. CLI commands | implemented | `brand`, `plan brand` |
+| 18. Help/discovery | implemented | cli help + slash /brand /plan /next |
+| 19. Tests | implemented | brand-scan.test.mjs + capabilities preset |
+| 20. Package boundaries | implemented | private `agentsam-sdk-brand` workspace |
+| 21. Backward compatibility | implemented | additive capabilities |
+| 22. E2E terminal demo | partial | CLI smoke; full interactive shell demo pending |
+
+**Not done yet (explicit):** `brand.apply` mutations, full multi-op TUI panel, deep shell free-text loop, campaign/theme.create inheritance executor.

package/docs/CLI_SHELL.md

@@ -55,6 +55,8 @@ Current controls include:
 /whoami      authenticated IAM identity + safe credential status
 /session     current cumulative token/cost/resume receipt
 /cf          bounded Cloudflare/Workers operations
+/connections live account / terminal / Worker / Cloudflare connection evidence
+/tunnel      real Cloudflare Tunnel picker backed by Wrangler
 /status      local project / DB / Git / PTY health
 /settings    project/runtime/terminal/model preferences
 /pwd         working directory
@@ -86,7 +88,7 @@ Provider files are machine-local and must not be group/world-readable on POSIX s
 
 `agentsam models` uses the credential internally for safe provider discovery but never returns the secret. Its public status reports only safe facts such as provider, configured state, source class, and provider-verified model availability.
 
-IAM login is also machine-local rather than repository state. A successful browser authentication may persist the `sdk_` bearer under `~/.agentsam/auth/session.json` with restrictive permissions. `agentsam whoami`, deploy, tunnel, and context detection can reuse that validated session. Project `.agentsam/config.json` remains portable and must not become a second identity database.
+IAM login is also machine-local rather than repository state. A successful browser authentication may persist the `sdk_` bearer under `~/.agentsam/auth/session.json` with restrictive permissions. `agentsam whoami`, deploy, and context detection can reuse that validated session. Cloudflare Tunnel management uses Wrangler's own authenticated Cloudflare identity rather than IAM bearer state. Project `.agentsam/config.json` remains portable and must not become a second identity database.
 
 ```bash
 agentsam whoami
@@ -209,7 +211,7 @@ SDK developers can preview rendering experiments from this repository, but those
 
 `agentsam init` owns portable repository/project setup. User identity, provider secrets, session history, execution approvals, and provider continuation state are machine/account runtime state and must not be written into portable project configuration.
 
-Local development does not require a cloud account. Cloud infrastructure is added intentionally.
+Local development does not require a cloud account. Cloud infrastructure is added intentionally. When Cloudflare Tunnel is selected, Agent Sam delegates discovery and lifecycle to Wrangler (`tunnel list`, `info`, `run`, `create`, and `quick-start`) instead of maintaining a parallel named-tunnel implementation.
 
 ## Design rule
 

package/docs/CMS_CONTEXTUAL_COMPOSER.md

@@ -0,0 +1,38 @@
+# CMS Editor — Agent Sam Contextual Composer
+
+24 Sept 2026 · build target for `apps/client-cms-editor` (agentsam-sdk), proven on Fuel & Free Time, then brought into Inner Animal Media.
+
+## Ideal-state packages (FNF = proving ground)
+
+These FNF packages are **examples of the ideal state**, not permanent homes. Each becomes an SDK-packaged prebuild:
+
+| Proving ground (FNF) | SDK target | Role |
+|---|---|---|
+| `packages/agentsam-workbench` | `@inneranimalmedia/agentsam-workbench` | miniAgentSam + contextual composer |
+| `packages/heuristic-theme` | `@inneranimalmedia/heuristic-theme` | **Stock CMS theme preset** |
+| `packages/commerce-analytics` | `@inneranimalmedia/commerce-analytics` | Commerce analytics surfaces |
+
+`agentsam create … --preset cms` should land on **heuristic-theme** as the basic stock theme.
+
+## Interaction loop (required)
+
+1. **Select** an object on the live canvas.
+2. **Ask** (or agent proactively offers) — right panel scopes to selection.
+3. **Suggest** — one primary suggestion card (action title + rationale + chevron), not a chat wall.
+4. **Accept** (card click) → generation starts (no extra confirm).
+5. **Generate** — polished gradient overlay on canvas + contained monospace code stream with soft gradient veil (trust/transparency, not approval UI). Phases: Reading selection → Drafting markup → Writing styles → Wiring settings.
+6. **Land** — gradient cross-fades to real block; left inspector flashes updated fields; composer posts confirmation.
+
+Left panel is always a real layers tree + property inspector (text, layout, typography preset, appearance, padding, remove) bound to the **same** block model the agent edits.
+
+## Implementation
+
+- Primitives: `packages/agentsam-workbench/src/agent/ContextualComposer.tsx` (+ CSS)
+- Host wiring: `apps/client-cms-editor/frontend/src/CmsAgentSurface.tsx` with `contextual`
+- Threads persist per page/site via `localStorage` (survive redock/resize — portable agent)
+
+## Open decisions (from spec)
+
+- Generation preview dock: default **inside right composer**; canvas keeps the gradient overlay.
+- Threads: persisted per project key; scoped optionally to selection without discarding other threads.
+- Pipeline: host-owned `planSuggestion` / `runGeneration` (AgentSam runtime / MCP) — demos ship with local stubs.

package/docs/MERKLE.md

@@ -68,3 +68,7 @@ const comparison = diffTrees(baseline, current);
 ```
 
 The library is local filesystem tooling. It adds no Worker bindings, user/workspace identity, or network calls. The interoperable content hash format is specified in [MERKLE_V1](../protocol/MERKLE_V1.md), and semantic identity in [FILEMETA_V1](../protocol/FILEMETA_V1.md).
+
+## AutoRAG use
+
+AutoRAG consumes this package's content root and optional semantic metadata root as source evidence. During a code plan it compares those roots with the previous generation, reports changed paths, and reuses unchanged parsed chunks/vectors where their content identity still matches. Merkle is deterministic filesystem evidence; it is not a dependency graph, an AST graph, a vector index, or a replacement for Git history.