feat: complete the Flect 1.0 live-canvas vision

.agents/skills/flect-quality/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: flect-quality
+description: Evaluate, improve, review, or release Flect against its canonical user-quality contract. Use for product-quality baselines, release readiness, user-outcome audits, evidence verification, gap prioritization, claim validation, dogfooding, or implementation work intended to move an FQ criterion to proven.
+---
+
+# Flect quality
+
+Use Flect's public behavior to prove user outcomes. Do not reconstruct the
+quality contract inside this skill.
+
+## Load the contract
+
+1. Read the repository `AGENTS.md`, `VISION.md`, `PRODUCT.md`,
+   `ARCHITECTURE.md`, `CONTRIBUTING.md`, and every nearer instruction file.
+2. Read `docs/product-quality.md` completely. It owns criteria, constituencies,
+   release gates, and proof classes.
+3. Read the current release claims in `README.md` and the relevant owning
+   documentation.
+4. Read existing reports under `docs/verification/` that claim evidence for
+   the criteria in scope.
+5. Inspect the worktree and record uncommitted-state caveats. Never discard or
+   overwrite unrelated work.
+
+## Select the operation
+
+- **Evaluate:** classify every criterion required by the requested release or
+  scope and write a dated baseline.
+- **Improve:** start from a frozen baseline, select the smallest independently
+  reviewable gap, and follow the repository's design, plan, TDD, and
+  verification workflow.
+- **Review:** compare a proposed change and its evidence with the affected
+  criteria; report missing behavior, weakened boundaries, and unsupported
+  claims before style concerns.
+- **Release:** prove every current release claim and every criterion required
+  by that release class. Any regression, unsupported claim, missing mandatory
+  evidence, or non-waivable gate failure blocks the release.
+
+Evaluation and improvement are separate phases. Freeze the observations before
+changing the behavior they describe.
+
+## Build an evidence map
+
+For every criterion in scope, record:
+
+- criterion identifier;
+- `unimplemented`, `partial`, `implemented`, `proven`, or `regressed`;
+- exact evidence path, command, workflow, host, date, and revision;
+- missing proof or observed failure;
+- release impact; and
+- existing GitHub issue, if any.
+
+Use only the proof classes required by the contract. Prefer the smallest public
+surface that establishes the whole outcome:
+
+- exported Effect contracts and Layers for deterministic behavior;
+- production Chromium for visible browser behavior;
+- the packaged application and public `flect` executable for native behavior;
+- adversarial tests for capabilities, credentials, sandboxes, extensions, and
+  recovery;
+- keyboard, assistive-technology, visual, and dogfooding evidence for outcomes
+  automation cannot judge alone;
+- clean artifacts and clean-machine workflows for release claims; and
+- public integration contracts for adopter outcomes.
+
+Source inspection may identify where to test. Prose, source strings, successful
+compilation, test names, screenshots without behavior, generated plans, and an
+agent's assertion cannot establish `proven`.
+
+## Exercise Flect publicly
+
+Use visible UI, public HTTP/SSE or MCP contracts, and the public `flect` AXI.
+Do not drive React internals, mutate browser storage, call private sidecar
+modes, or treat direct database or journal inspection as user evidence.
+
+Start agent-first discovery with `flect`, then request only the bounded state
+needed. Keep outside control disabled unless the user explicitly enables it in
+the protected shell. Revoke it when live inspection is finished.
+
+For a complete supported-slice baseline, normally run:
+
+```bash
+bun install --frozen-lockfile
+bun run check:quality
+bun run check:all
+```
+
+Run `bun run test:pi-smoke` only when approved provider authentication is
+available and a live turn is required. Never capture credentials, private
+control capabilities, unbounded logs, or sensitive product output.
+
+## Record the baseline
+
+Write `docs/verification/YYYY-MM-DD-<scope>-verification.md`. Include:
+
+1. scope, release class, date, revision, branch, dirty-state caveat, and hosts;
+2. commands and public workflows actually run;
+3. one classification for every criterion in scope;
+4. exact evidence and limitations;
+5. current claims contradicted by behavior; and
+6. unproven release gates and their issue links.
+
+Keep a baseline immutable after it is frozen except to correct factual or
+redaction errors. A later run creates a later report and may supersede it.
+
+## Reconcile delivery work
+
+Use `gh-axi` for GitHub inspection and mutation. Search open and closed issues
+before creating anything. Do not create one issue per criterion mechanically.
+
+Create the smallest independently reviewable issue that closes a real behavior
+gap. Each issue names:
+
+- affected `FQ-*` identifiers;
+- observable acceptance criteria;
+- exact proof classes and public workflows;
+- dependencies and explicit non-goals;
+- owning documentation; and
+- security, recovery, portability, or accessibility constraints that must
+  remain true.
+
+Place delivery issues in the dedicated Flect organization project. The project
+owns live priority, dependency order, release slice, assignee, and status. Do
+not copy that status into `docs/product-quality.md`.
+
+## Improve one vertical slice
+
+Before behavior changes, use the repository's required brainstorming and plan
+workflow. Split independent subsystems into separate reviewed designs and
+plans. Start observable behavior with a failing test and use Effect throughout
+the application architecture as required by `AGENTS.md`.
+
+Require:
+
+- real Chromium for UI, shaping, import, accessibility, or browser sandbox
+  behavior;
+- packaged-host and public AXI dogfooding for native or external-control
+  behavior;
+- adversarial negative tests for new authority or extension boundaries;
+- deterministic recovery tests for changes affecting candidates, persistence,
+  extensions, or accepted state; and
+- updates to the canonical documentation owner without parallel capability
+  lists or implementation claims.
+
+Implementation does not make its own criterion `proven`. Re-run the required
+public evidence after the change and record a new verification report.
+
+## Fail closed
+
+Immediately report and treat as release-blocking when applicable:
+
+- shipped behavior contradicts a current claim;
+- credentials or private capabilities appear in output or artifacts;
+- shaped or extension code can bypass typed capabilities or recovery;
+- acceptance, rollback, safe mode, or outside-control revocation is not
+  deterministic;
+- evidence is missing, stale, scoped to the wrong host, or derived only from
+  implementation details; or
+- a regression is obscured by changing prose or lowering the criterion.

.agents/skills/flect-quality/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Flect Quality"
+  short_description: "Prove and improve Flect user outcomes"
+  default_prompt: "Use $flect-quality to evaluate Flect against its canonical user-quality contract and produce evidence-backed gaps."

.agents/skills/flect/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: flect
+description: Operate and inspect a running Flect interface through its bounded agent-first command surface. Use when an agent needs to inspect Flect state, read operation evidence, invoke visible actions, shape an interface, manage revisions or models, debug a Flect workspace, or configure explicit native Flect integrations.
+---
+
+# Flect
+
+Use the public `flect` command. Treat it as the authoritative command surface for the running interface; do not drive React, storage, broker internals, or private runtime binaries directly.
+
+## Start with discovery
+
+1. Run `flect` with no arguments for content-first discovery and relevant next actions.
+2. Run `flect inspect` only when more workspace detail is needed.
+3. Run `flect action list` before invoking a product action.
+4. Prefer default bounded TOON output. Add `--json` only for a consumer that requires JSON and `--full` only when complete authorized text is necessary.
+
+## Respect authority
+
+- App Agent uses the accepted product and its projected actions. It does not shape or accept revisions.
+- Shaper changes interface candidates inside its disposable sandbox. Run `flect interface validate <path>` before `flect interface propose <path>`; proposal acceptance remains a user decision.
+- Outside agents require the user's explicit local-control grant before live workspace operations become available.
+- Help visibility is not authorization. Treat structured `unauthorized`, `conflict`, `rejected`, and `unavailable` results as definitive.
+
+## Command map
+
+| Command | Purpose | Intended caller |
+| --- | --- | --- |
+| `flect` | Show content-first live discovery and relevant next commands. | outside agent, App Agent, Shaper |
+| `flect inspect [--fields <closed-list>]` | Inspect validated live workspace state. | outside agent, App Agent, Shaper |
+| `flect logs [--limit <n>] [--role <app\|shaper>]` | Read bounded, correlated operation evidence. | outside agent, App Agent, Shaper |
+| `flect watch [--after <sequence>]` | Wait for the next reactive workspace event. | outside agent, App Agent, Shaper |
+| `flect target <use\|shape>` | Select the visible Use or Shape conversation explicitly. | outside agent, App Agent |
+| `flect mode set <edit\|run>` | Compatibility alias for selecting Shape or Use. | outside agent, App Agent |
+| `flect prompt <text>\|--stdin` | Ask App Agent to use the accepted product. | outside agent, App Agent |
+| `flect shape <instruction>\|--stdin` | Ask Shaper to prepare a validated interface proposal. | outside agent, Shaper |
+| `flect cancel <app\|shaper>` | Stop the selected running agent turn. | outside agent |
+| `flect action list\|inspect\|invoke` | Discover and invoke actions projected by the visible interface. | outside agent, App Agent |
+| `flect product invoke <operation-id> [--input <json>]` | Invoke a registered product operation without raw HTTP access. | outside agent, App Agent |
+| `flect permissions list\|revoke <decision-id>` | Inspect product permission lifecycle or revoke a visible decision; grants remain protected UI decisions. | outside agent, App Agent, Shaper |
+| `flect interface inspect\|schema\|validate\|propose` | Inspect or propose interface documents inside Shaper's sandbox. | Shaper |
+| `flect proposal accept\|reject` | Resolve the current validated preview as a protected user decision. | outside agent, App Agent |
+| `flect revision list\|rollback` | Inspect revision state or request deterministic rollback. | outside agent, App Agent |
+| `flect repository status` | Inspect canonical Git refs, isolation, and conflict state. | outside agent, App Agent, Shaper |
+| `flect share list\|inspect` | Inspect bounded inactive shared candidates and retained installations. | outside agent, App Agent, Shaper |
+| `flect share open-url\|open-git\|reject\|export` | Route bounded shared-source actions through protected user review. | outside agent |
+| `flect share checkpoint <share-id> --at <commit> --write <share-path> <sandbox-path> --message <text>` | Checkpoint bounded Shaper sandbox files onto an exact retained share fork. | Shaper |
+| `flect share resolve <share-id> --base <commit> --upstream <commit> --fork <commit> --write <share-path> <sandbox-path> --message <text>` | Submit an exact bounded Shaper resolution for every reviewed shared conflict path. | Shaper |
+| `flect model list\|select\|favorite` | Inspect and select Pi-backed models without exposing credentials. | outside agent, App Agent, Shaper |
+| `flect extensions list\|describe\|call` | Discover and call enabled portable extensions for the current role and binding. | outside agent, App Agent, Shaper |
+| `flect trusted-extensions enable\|disable <app\|shaper>` | Set opt-in loading for the selected Pi role's outside extensions. | outside agent, App Agent |
+| `flect safe enter\|restore` | Enter compiled recovery or restore the last-known-good interface. | outside agent, App Agent |
+| `flect rail collapse\|expand\|width <pixels>` | Set the protected agent rail presentation. | outside agent, App Agent |
+| `flect control status\|disable` | Inspect or revoke explicitly granted outside control. | outside agent |
+| `flect context --host <codex\|claude\|opencode>` | Emit bounded static guidance plus available live Flect context. | outside agent |
+| `flect setup status` | Inspect the fixed shell link and opt-in agent integrations. | outside agent |
+| `flect setup shell install\|remove` | Manage only ~/.local/bin/flect for the installed desktop app. | outside agent |
+| `flect setup agent install\|remove <codex\|claude\|opencode>` | Manage one ownership-marked ambient context integration. | outside agent |
+| `flect setup uninstall inspect\|prepare` | Inspect or remove only Flect-owned integrations before moving the app to Trash. | outside agent |
+| `flect mcp` | Serve the compact MCP adapter over stdio. | outside agent |
+
+## Keep the boundary safe
+
+- Never request or print model credentials, the local-control capability, private runtime flags, or unbounded logs.
+- Use explicit set-shaped commands instead of inventing toggles or raw payload escape hatches.
+- Read the returned receipt and resulting workspace state before deciding whether another command is needed.
+- Use `flect logs --limit 20` for bounded failure evidence and safe mode for deterministic recovery.

.github/workflows/quality.yml

@@ -0,0 +1,74 @@
+name: Flect quality
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+    inputs:
+      failure_probe:
+        description: Prove that the public quality check fails closed
+        required: false
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    name: Flect quality gate
+    runs-on: macos-15
+    timeout-minutes: 45
+    env:
+      CI: true
+    steps:
+      - name: Check out the exact revision
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803
+        with:
+          persist-credentials: false
+
+      - name: Install the pinned Bun runtime
+        uses: oven-sh/setup-bun@b7a1c7ccf290d58743029c4f6903da283811b979
+        with:
+          bun-version: "1.3.14"
+          no-cache: true
+
+      - name: Install the pinned Rust toolchain
+        uses: dtolnay/rust-toolchain@2c7215f132e9ebf062739d9130488b56d53c060c
+        with:
+          toolchain: "1.93.0"
+          components: rustfmt
+
+      - name: Install locked dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Install the pinned Chromium runtime
+        run: bunx playwright install chromium
+
+      - name: Run the canonical quality gate
+        run: bun run check:all
+
+      - name: Deliberate failure probe
+        if: github.event_name == 'workflow_dispatch' && inputs.failure_probe
+        run: bun -e 'throw new Error("Deliberate Flect CI failure probe.")'
+
+      - name: Upload bounded browser failure evidence
+        if: failure() && !cancelled()
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4
+        with:
+          name: flect-browser-failure-${{ github.run_id }}
+          path: |
+            test-results/**
+            !test-results/control-state/**
+          if-no-files-found: ignore
+          retention-days: 7
+          compression-level: 9
+          include-hidden-files: false

.gitignore

@@ -1,8 +1,11 @@
 .DS_Store
 .worktrees/
-.repos/effect
+.repos/
 node_modules/
+.astro/
 dist/
+dist-spa/
+dist-product-sdk/
 dist-release/
 coverage/
 playwright-report/
@@ -13,3 +16,4 @@ src-tauri/binaries/
 .env
 .env.*
 !.env.example
+.tauri-signing-key*