scene-capability-engine 3.6.32 → 3.6.36

package/docs/magicball-cli-invocation-examples.md

@@ -0,0 +1,336 @@
+# MagicBall CLI Invocation Examples
+
+## Goal
+
+Provide copy-ready invocation examples for the most common MagicBall -> SCE integration flows.
+
+This document is optimized for frontend integration, local debugging, and CLI smoke verification.
+It is not the main source of architecture or product policy.
+
+Use this together with:
+- `docs/magicball-ui-surface-checklist.md`
+- `docs/magicball-frontend-state-and-command-mapping.md`
+- `docs/magicball-write-auth-adaptation-guide.md`
+
+## Conventions
+
+Assume:
+- `app_key = customer-order-demo`
+- current workspace already uses the intended project root
+- all commands request machine-readable JSON via `--json`
+
+## 1. Workspace Bootstrap
+
+### 1.1 App bundle identity
+```bash
+sce app bundle show --app customer-order-demo --json
+```
+
+Expected use:
+- cache `app_id`
+- cache `app_key`
+- cache app-level bundle bindings
+
+### 1.2 Serialized mode-home bootstrap
+Run in this order only:
+
+```bash
+sce mode application home --app customer-order-demo --json
+sce mode ontology home --app customer-order-demo --json
+sce mode engineering home --app customer-order-demo --json
+sce app engineering show --app customer-order-demo --json
+```
+
+Recommended frontend rule:
+- do not parallelize these four calls during current verification window
+
+## 2. Application Mode Examples
+
+### 2.1 Read application home
+```bash
+sce mode application home --app customer-order-demo --json
+```
+
+Typical fields MagicBall cares about:
+- `summary.app_name`
+- `summary.runtime_version`
+- `summary.install_status`
+- `summary.release_count`
+- `view_model.current_release`
+
+### 2.2 Read runtime releases
+```bash
+sce app runtime releases --app customer-order-demo --json
+```
+
+### 2.3 Install a release
+```bash
+sce app runtime install --app customer-order-demo --release rel-2026-03 --json
+```
+
+### 2.4 Activate a release
+```bash
+sce app runtime activate --app customer-order-demo --release rel-2026-03 --json
+```
+
+## 3. Ontology Mode Examples
+
+### 3.1 Read ontology home
+```bash
+sce mode ontology home --app customer-order-demo --json
+```
+
+### 3.2 Read triad summary
+```bash
+sce ontology triad summary --json
+```
+
+### 3.3 Read ER / BR / DL tables
+```bash
+sce ontology er list --json
+sce ontology br list --json
+sce ontology dl list --json
+```
+
+### 3.4 Read starter-seed preview
+```bash
+sce ontology seed show --profile customer-order-demo --json
+```
+
+### 3.5 Apply starter seed
+```bash
+sce ontology seed apply --profile customer-order-demo --json
+```
+
+### 3.6 Refresh chain after successful seed apply
+Run in this order:
+
+```bash
+sce mode ontology home --app customer-order-demo --json
+sce ontology triad summary --json
+sce ontology er list --json
+sce ontology br list --json
+sce ontology dl list --json
+```
+
+## 4. Engineering Mode Examples
+
+### 4.1 Read engineering home
+```bash
+sce mode engineering home --app customer-order-demo --json
+```
+
+### 4.2 Read PM tabs
+```bash
+sce pm requirement list --json
+sce pm tracking board --json
+sce pm planning board --json
+sce pm change list --json
+sce pm issue board --json
+```
+
+### 4.3 Read assurance tabs
+```bash
+sce assurance resource status --json
+sce assurance logs views --json
+sce assurance backup list --json
+sce assurance config switches --json
+```
+
+### 4.4 Read engineering project detail
+```bash
+sce app engineering show --app customer-order-demo --json
+```
+
+## 5. Write Authorization Examples
+
+### 5.1 Inspect current authorization status
+```bash
+sce auth status --json
+```
+
+### 5.2 Grant lease for PM editing
+```bash
+sce auth grant --scope pm:requirement:upsert --reason "edit requirement from MagicBall" --json
+```
+
+### 5.3 Grant lease for ontology editing
+```bash
+sce auth grant --scope ontology:er:upsert,ontology:br:upsert,ontology:dl:upsert --reason "edit ontology from MagicBall" --json
+```
+
+### 5.4 Use returned lease on a write command
+```bash
+sce pm requirement upsert --input requirement.json --auth-lease <lease-id> --json
+```
+
+### 5.5 Re-check a lease
+```bash
+sce auth status --lease <lease-id> --json
+```
+
+### 5.6 Revoke a lease
+```bash
+sce auth revoke --lease <lease-id> --json
+```
+
+## 6. PM Write Examples
+
+### 6.1 Requirement upsert
+```bash
+sce pm requirement upsert --input requirement.json --json
+```
+
+Example `requirement.json`:
+```json
+{
+  "requirement_id": "REQ-UI-001",
+  "title": "Render requirement list in engineering mode",
+  "source_request": "MagicBall engineering tab integration",
+  "status": "draft",
+  "priority": "P1"
+}
+```
+
+### 6.2 Tracking upsert
+```bash
+sce pm tracking upsert --input tracking.json --json
+```
+
+Example `tracking.json`:
+```json
+{
+  "tracking_id": "TRK-UI-001",
+  "requirement_id": "REQ-UI-001",
+  "current_stage": "clarifying",
+  "status": "normal",
+  "next_action": "Wire engineering tracking tab"
+}
+```
+
+### 6.3 Issue upsert
+```bash
+sce pm issue upsert --input issue.json --json
+```
+
+Example `issue.json`:
+```json
+{
+  "issue_id": "BUG-UI-001",
+  "title": "Engineering issue tab does not refresh",
+  "source": "review",
+  "severity": "medium",
+  "status": "new"
+}
+```
+
+## 7. Task Feedback And Timeline Examples
+
+### 7.1 Read task feedback for a job
+```bash
+sce studio events --job <job-id> --json
+```
+
+MagicBall should prefer:
+- `task.feedback_model`
+- `task.mb_status`
+- raw `event[]` only in advanced/audit mode
+
+### 7.2 Read timeline list
+```bash
+sce timeline list --limit 20 --json
+```
+
+### 7.3 Read timeline detail
+```bash
+sce timeline show <snapshot-id> --json
+```
+
+## 8. Suggested Frontend Wrapper Pattern
+
+### 8.1 Node/Electron shell wrapper
+```ts
+async function runSceJson(args: string[]) {
+  const result = await invokeShell(['sce', ...args]);
+  if (result.exitCode !== 0) {
+    throw {
+      command: ['sce', ...args].join(' '),
+      exitCode: result.exitCode,
+      stdout: result.stdout,
+      stderr: result.stderr,
+      retryable: true
+    };
+  }
+  return JSON.parse(result.stdout);
+}
+```
+
+### 8.2 Serialized workspace bootstrap wrapper
+```ts
+async function loadWorkspace(appKey: string) {
+  const appBundle = await runSceJson(['app', 'bundle', 'show', '--app', appKey, '--json']);
+  const applicationHome = await runSceJson(['mode', 'application', 'home', '--app', appKey, '--json']);
+  const ontologyHome = await runSceJson(['mode', 'ontology', 'home', '--app', appKey, '--json']);
+  const engineeringHome = await runSceJson(['mode', 'engineering', 'home', '--app', appKey, '--json']);
+  const engineeringDetail = await runSceJson(['app', 'engineering', 'show', '--app', appKey, '--json']);
+
+  return {
+    appBundle,
+    applicationHome,
+    ontologyHome,
+    engineeringHome,
+    engineeringDetail
+  };
+}
+```
+
+## 9. Failure Logging Pattern
+
+When a command fails, MagicBall should preserve:
+- command string
+- exit code
+- stderr
+- stdout if any
+- page/section where failure happened
+- retry action name
+
+Suggested error bundle:
+
+```json
+{
+  "command": "sce mode ontology home --app customer-order-demo --json",
+  "page": "ontology",
+  "section": "summary",
+  "exit_code": 1,
+  "stderr": "database is locked",
+  "retryable": true
+}
+```
+
+## 10. Recommended Smoke Flow For Local Integration
+
+Run this full sequence when verifying MagicBall local integration:
+
+```bash
+sce app bundle show --app customer-order-demo --json
+sce mode application home --app customer-order-demo --json
+sce mode ontology home --app customer-order-demo --json
+sce mode engineering home --app customer-order-demo --json
+sce app engineering show --app customer-order-demo --json
+sce ontology triad summary --json
+sce pm requirement list --json
+sce assurance resource status --json
+sce auth status --json
+```
+
+If ontology is empty and product wants starter data:
+
+```bash
+sce ontology seed show --profile customer-order-demo --json
+sce ontology seed apply --profile customer-order-demo --json
+sce mode ontology home --app customer-order-demo --json
+sce ontology triad summary --json
+sce ontology er list --json
+sce ontology br list --json
+sce ontology dl list --json
+```

package/docs/magicball-frontend-state-and-command-mapping.md

@@ -0,0 +1,244 @@
+# MagicBall Frontend State And Command Mapping
+
+## Goal
+
+Turn the current SCE integration defaults into a concrete frontend mapping table for MagicBall.
+
+This document focuses on:
+- page-level state ownership
+- command-to-action mapping
+- success / empty / error rendering rules
+- retry and refresh behavior
+
+Use this together with:
+- `docs/magicball-sce-adaptation-guide.md`
+- `docs/magicball-mode-home-and-ontology-empty-state-playbook.md`
+- `docs/magicball-write-auth-adaptation-guide.md`
+
+## 1. Integration Surfaces
+
+The current frontend-sensitive surfaces are:
+1. app bootstrap and mode-home loading
+2. ontology empty-state and starter-seed initialization
+3. write-error presentation and retry boundaries
+4. timeline / task feedback handoff points
+
+## 2. Page State Ownership
+
+### 2.1 App Workspace Shell
+
+This state belongs to the top-level app workspace shell.
+
+Recommended shape:
+
+```ts
+interface AppWorkspaceState {
+  appKey: string
+  appBundle: Record<string, unknown> | null
+  applicationHome: Record<string, unknown> | null
+  ontologyHome: Record<string, unknown> | null
+  engineeringHome: Record<string, unknown> | null
+  engineeringDetail: Record<string, unknown> | null
+  boot: ModeBootState
+}
+```
+
+Owned commands:
+- `sce app bundle show --app <app-key> --json`
+- `sce mode application home --app <app-key> --json`
+- `sce mode ontology home --app <app-key> --json`
+- `sce mode engineering home --app <app-key> --json`
+- `sce app engineering show --app <app-key> --json`
+
+Rule:
+- this shell owns mode bootstrap and should not delegate command ordering to nested tabs
+
+### 2.2 Ontology Page State
+
+Recommended shape:
+
+```ts
+interface OntologyPageState {
+  ontologyHome: Record<string, unknown> | null
+  triadSummary: Record<string, unknown> | null
+  erList: Record<string, unknown> | null
+  brList: Record<string, unknown> | null
+  dlList: Record<string, unknown> | null
+  starterSeed: {
+    suggested: boolean
+    profile: string | null
+    guidance: string | null
+  }
+  emptyState: {
+    visible: boolean
+    reason: string | null
+  }
+  seedFlow: {
+    loading: boolean
+    confirming: boolean
+    lastError: string | null
+  }
+}
+```
+
+Owned commands:
+- `sce mode ontology home --app <app-key> --json`
+- `sce ontology triad summary --json`
+- `sce ontology er list --json`
+- `sce ontology br list --json`
+- `sce ontology dl list --json`
+- `sce ontology seed show --profile customer-order-demo --json`
+- `sce ontology seed apply --profile customer-order-demo --json`
+
+Rule:
+- ontology page owns empty-state detection and post-seed refresh chain
+
+### 2.3 Command Failure State
+
+Recommended shared shape:
+
+```ts
+interface CommandFailureState {
+  command: string
+  scope: 'read' | 'write'
+  page: string
+  stderr: string
+  stdout: string | null
+  exitCode: number | null
+  occurredAt: string
+  retryable: boolean
+}
+```
+
+Rule:
+- preserve exact command failure data for copy, retry, and AI-assisted diagnosis
+- do not collapse all failures into a single generic message
+
+## 3. Bootstrap Command Mapping
+
+| UI event | SCE command | State target | Success behavior | Failure behavior |
+| --- | --- | --- | --- | --- |
+| Open app workspace | `sce app bundle show --app <app-key> --json` | `appBundle` | cache app identity and bundle bindings | stop boot and show workspace-level error |
+| Bootstrap step 1 | `sce mode application home --app <app-key> --json` | `applicationHome` | render app hero / release status | stop boot, allow step retry |
+| Bootstrap step 2 | `sce mode ontology home --app <app-key> --json` | `ontologyHome` | render ontology summary shell | keep app section visible, allow step retry |
+| Bootstrap step 3 | `sce mode engineering home --app <app-key> --json` | `engineeringHome` | render engineering summary shell | keep prior sections visible, allow step retry |
+| Bootstrap step 4 | `sce app engineering show --app <app-key> --json` | `engineeringDetail` | render repo/workspace detail | keep engineering summary visible, allow step retry |
+
+Implementation rule:
+- all four steps execute sequentially
+- each step updates `boot.activeStep`
+- each success appends to `boot.completedSteps`
+- each failure writes a `CommandFailureState`
+
+## 4. Ontology Empty-State Mapping
+
+| Detection input | Frontend interpretation | UI action |
+| --- | --- | --- |
+| `mode ontology home` returns `starter_seed` guidance | project is seed-capable | show helper text + initialize button |
+| `ontology triad summary` shows zero/missing triads | ontology coverage is not initialized | keep summary visible, do not treat as backend failure |
+| `er/br/dl list` all empty | ontology asset space is empty | show empty-state card |
+| one or more lists contain items | ontology is initialized | hide empty-state card |
+
+Empty-state visibility rule:
+- show empty-state only when the table/list surfaces are empty and summary also indicates zero/missing coverage
+- do not show empty-state if one of ER/BR/DL already has real items
+
+## 5. Starter Seed Command Mapping
+
+| UI event | SCE command | State target | Success behavior | Failure behavior |
+| --- | --- | --- | --- | --- |
+| Open seed confirmation | `sce ontology seed show --profile customer-order-demo --json` | `seedFlow.confirming` | show preview of starter content | allow direct apply fallback if preview fails but command is optional |
+| Confirm initialize | `sce ontology seed apply --profile customer-order-demo --json` | `seedFlow.loading` | run post-seed refresh chain | keep empty-state card visible and preserve exact error |
+| Refresh after seed | `sce mode ontology home --app <app-key> --json` | `ontologyHome` | update summary/seed hint | show section-level error |
+| Refresh after seed | `sce ontology triad summary --json` | `triadSummary` | update triad readiness | show section-level error |
+| Refresh after seed | `sce ontology er list --json` | `erList` | populate ER table | show table-level error |
+| Refresh after seed | `sce ontology br list --json` | `brList` | populate BR table | show table-level error |
+| Refresh after seed | `sce ontology dl list --json` | `dlList` | populate DL table | show table-level error |
+
+Important rule:
+- seed apply is user-triggered only
+- refresh chain is automatic once seed apply succeeds
+
+## 6. Error Rendering Contract
+
+### 6.1 Read Errors
+
+Read errors should be rendered inline at the section that failed.
+
+Examples:
+- ontology summary failed -> show summary card error, not full page crash
+- ER list failed -> show ER table error, keep BR/DL areas usable
+- engineering detail failed -> keep engineering summary visible
+
+### 6.2 Write Errors
+
+Write errors should expose:
+- exact command
+- exit code
+- stderr
+- retry action
+- copy error action
+
+Recommended write-error card fields:
+- title
+- short reason
+- command snippet
+- copy button
+- retry button
+- `Ask AI to help fix` action if MagicBall already supports it
+
+### 6.3 Retry Boundary Rule
+
+Retry only the failed operation.
+Do not blindly rerun the entire page bootstrap or seed workflow unless the state model requires it.
+
+## 7. Suggested UI Actions
+
+### 7.1 Workspace Shell
+
+Buttons:
+- `Retry current step`
+- `Reload app workspace`
+- `Copy command error`
+
+### 7.2 Ontology Empty-State Card
+
+Buttons:
+- `Initialize starter ontology`
+- `Continue with empty ontology`
+- `Retry summary`
+
+### 7.3 Seed Failure Card
+
+Buttons:
+- `Retry initialization`
+- `Copy command error`
+- `Continue with empty ontology`
+
+## 8. Timeline And Task Handoff
+
+This document does not redefine task/timeline contracts.
+Use existing SCE view contracts for those surfaces:
+- `docs/magicball-task-feedback-timeline-guide.md`
+- `docs/agent-runtime/magicball-contract-index.md`
+
+Recommended connection point:
+- when a write or seed command fails, store the exact command failure bundle so MagicBall can pass it into its AI assistant or timeline/task views later
+
+## 9. Minimal Acceptance Checklist
+
+MagicBall can consider this mapping implemented when:
+- one app workspace shell owns mode bootstrap ordering
+- one ontology page state owns empty-state detection and seed flow
+- each failing command renders at the correct section boundary
+- every retry button retries only one failed command
+- every write error can be copied directly for AI-assisted diagnosis
+
+## 10. Suggested Implementation Order
+
+1. workspace shell boot state
+2. serialized bootstrap commands
+3. ontology empty-state card
+4. seed confirmation + apply flow
+5. section-level error cards
+6. error copy / retry actions

package/docs/magicball-integration-doc-index.md

@@ -0,0 +1,137 @@
+# MagicBall Integration Doc Index
+
+## Goal
+
+Provide one short entry document for MagicBall engineers to know:
+- which SCE-facing document to read first
+- which document to use for a specific frontend concern
+- which document is contract, checklist, tracker, or product policy
+
+This file should stay short.
+It is a navigation layer, not a new source of truth.
+
+## Current Entry Set
+
+These are the current first-line integration documents:
+- `docs/magicball-sce-adaptation-guide.md`
+- `docs/magicball-ui-surface-checklist.md`
+- `docs/magicball-mode-home-and-ontology-empty-state-playbook.md`
+- `docs/magicball-frontend-state-and-command-mapping.md`
+- `docs/magicball-cli-invocation-examples.md`
+- `docs/magicball-write-auth-adaptation-guide.md`
+- `docs/magicball-task-feedback-timeline-guide.md`
+- `docs/magicball-integration-issue-tracker.md`
+
+## Recommended Reading Order
+
+1. `docs/magicball-sce-adaptation-guide.md`
+   - primary integration overview
+   - command surfaces and three-mode entry model
+
+2. `docs/magicball-adaptation-task-checklist-v1.md`
+   - implementation checklist
+   - milestone-oriented execution order
+
+3. `docs/magicball-mode-home-and-ontology-empty-state-playbook.md`
+   - two active frontend-sensitive defaults
+   - serialized mode-home loading
+   - ontology empty-state and starter-seed behavior
+
+4. `docs/magicball-frontend-state-and-command-mapping.md`
+   - page state ownership
+   - command-to-action mapping
+   - error and retry boundaries
+
+5. `docs/magicball-write-auth-adaptation-guide.md`
+   - write authorization and lease handling
+
+6. `docs/magicball-task-feedback-timeline-guide.md`
+   - task feedback cards
+   - timeline view integration
+
+7. `docs/magicball-cli-invocation-examples.md`
+   - copy-ready CLI examples
+   - wrapper and smoke verification patterns
+
+8. `docs/magicball-integration-issue-tracker.md`
+   - current cross-project truth
+   - only open issues, active decisions, and verified resolutions
+
+## Use By Topic
+
+### I need to bootstrap the three-mode app shell
+Use:
+- `docs/magicball-sce-adaptation-guide.md`
+- `docs/magicball-mode-home-and-ontology-empty-state-playbook.md`
+- `docs/magicball-frontend-state-and-command-mapping.md`
+
+### I need to implement ontology empty-state and starter seed
+Use:
+- `docs/magicball-mode-home-and-ontology-empty-state-playbook.md`
+- `docs/magicball-frontend-state-and-command-mapping.md`
+- `docs/magicball-integration-issue-tracker.md`
+
+### I need to implement write actions safely
+Use:
+- `docs/magicball-write-auth-adaptation-guide.md`
+- `docs/magicball-frontend-state-and-command-mapping.md`
+- `docs/magicball-cli-invocation-examples.md`
+
+### I need copy-ready command examples for local integration
+Use:
+- `docs/magicball-cli-invocation-examples.md`
+
+### I need to build task cards and timeline panels
+Use:
+- `docs/magicball-task-feedback-timeline-guide.md`
+- `docs/agent-runtime/magicball-contract-index.md`
+
+### I need to know what is still open between MagicBall and SCE
+Use:
+- `docs/magicball-integration-issue-tracker.md`
+
+## Document Roles
+
+| Document | Role | Should change often? |
+| --- | --- | --- |
+| `magicball-sce-adaptation-guide.md` | main overview | low |
+| `magicball-adaptation-task-checklist-v1.md` | execution checklist | medium |
+| `magicball-mode-home-and-ontology-empty-state-playbook.md` | frontend behavior policy | medium |
+| `magicball-frontend-state-and-command-mapping.md` | frontend implementation mapping | medium |
+| `magicball-write-auth-adaptation-guide.md` | auth/write behavior | low |
+| `magicball-task-feedback-timeline-guide.md` | task/timeline integration | low |
+| `magicball-cli-invocation-examples.md` | copy-ready command examples | medium |
+| `magicball-integration-issue-tracker.md` | live cross-project tracker | high |
+
+## Secondary References
+
+These remain useful, but they are not first-read integration entry documents:
+- `docs/magicball-capability-iteration-ui.md`
+- `docs/magicball-capability-iteration-api.md`
+- `docs/magicball-capability-library.md`
+
+Use them when MagicBall is specifically implementing capability iteration / capability library flows.
+
+## Historical Foundation Drafts
+
+These documents are still worth keeping as architecture history, but should not drive current integration work directly:
+- `docs/magicball-app-bundle-sqlite-and-command-draft.md`
+- `docs/magicball-three-mode-alignment-plan.md`
+
+If guidance in these drafts conflicts with the current entry set, prefer the current entry set.
+
+## Current High-Priority Defaults
+
+As of the current tracker state:
+- `mode * home` stays serialized during `Issue 001` verification
+- fresh ontology pages use `fallback + optional seed apply`
+- seed apply stays explicit and user-triggered
+- command failures should be preserved in copyable form for AI-assisted diagnosis
+
+## Maintenance Rule
+
+When a new MagicBall-facing SCE document is added:
+- add it here only if it changes implementation behavior or cross-project coordination
+- do not add deep design drafts unless they are still active implementation inputs
+- after the current doc baseline, prefer feedback-driven updates over proactive document expansion
+- if there is no new real integration blocker, keep the current entry set stable