feat: add extraction schema, sidebar nav, few-shot prompting, and prompt settings

Overhaul extraction pipeline with new TradeItem model, conversation flow,
and dedicated extraction endpoint. Add sidebar navigation with NavMenu
component and landing page. Introduce few-shot prompting service and
tests. Add prompt settings and email upload specs. Update OpenSpec
tooling with improved export-spec and extract-feature commands. Archive
completed changes and export full specs.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.claude/commands/opsx/export-spec.md

@@ -54,7 +54,33 @@ Instead of retyping code, you retype a compact spec. The AI on the sandbox gener
 
    This shapes what the spec assumes vs what it must specify.
 
-5. **Generate the portable spec**
+5. **Capture the target GUI layout**
+
+   If the feature has a UI component, the spec MUST include the target's layout context.
+   Without it, the AI will generate components that conflict with the existing shell.
+
+   Ask the user:
+   > "Does the target app have an existing GUI shell? If so, share:
+   > 1. A **screenshot** (drag/drop or file path) — most information-dense
+   > 2. Or describe: AppBar (height? Dense?), Sidebar/Drawer (width? toggled?),
+   >    MainContent area, any fixed elements"
+
+   If a screenshot is provided, extract:
+   - AppBar type and height (Dense=48px, Regular=64px, custom)
+   - Sidebar/Drawer presence, width, toggle behavior
+   - Main content area constraints
+   - Existing navigation items
+
+   Then ask:
+   > "How should this feature integrate into the target?
+   > 1. Feature name in the target (e.g., 'Sales Assistant' not 'Chat')
+   > 2. Route path (e.g., `/sales-assistant`)
+   > 3. Navigation: new sidebar item? AppBar button? Floating panel?"
+
+   Generate an **ASCII layout diagram** showing exactly where the feature renders,
+   and include it in both the spec and the OpenSpec design.md.
+
+6. **Generate the portable spec**
 
    Create a single markdown document that is:
    - **Compact**: Target ~30-50 lines for a medium feature
@@ -68,6 +94,21 @@ Instead of retyping code, you retype a compact spec. The AI on the sandbox gener
    # Feature: <Name>
    ## Target: <project name> (<stack>)
 
+   ## Assumes
+   <what must already exist on the target>
+
+   ## Integration Rule
+   This feature is additive only. DO NOT modify existing files, components,
+   services, or patterns in the target. If the target already has an equivalent
+   service, use it instead of creating a new one. If a task conflicts with
+   existing target code, skip it and note the conflict. Existing applicationX
+   code takes precedence over this spec in all cases.
+
+   ## Target Layout
+   <ASCII diagram showing the target app shell and where this feature renders>
+   <AppBar height, Sidebar width, MainContent constraints>
+   <Feature name, route, navigation integration point>
+
    ## Packages
    <list with versions>
 
@@ -83,6 +124,11 @@ Instead of retyping code, you retype a compact spec. The AI on the sandbox gener
    ## Contracts
    <API shapes, model definitions — things that MUST be exact>
 
+   ## Critical Patterns
+   <Exact code snippets for traps the AI will otherwise get wrong>
+   <Show the POSITIVE pattern to copy, not just "don't use X">
+   <Include WHY — the mechanism behind the trap>
+
    ## Wiring
    <DI registration, middleware order, config keys — dependency order>
 
@@ -97,20 +143,26 @@ Instead of retyping code, you retype a compact spec. The AI on the sandbox gener
    - Only specify non-obvious behavior
    - Omit anything the AI would do by default
 
-6. **Estimate typing effort**
+7. **Estimate typing effort**
 
    Count characters in the spec. Compare to the code recipe equivalent.
    Show the compression ratio.
 
-7. **Optionally generate an OpenSpec-compatible version**
+8. **Optionally generate an OpenSpec-compatible version**
 
    If the target has OpenSpec, also generate:
+   - A **config.yaml** template — adapted context for the target project, with placeholders
    - A `proposal.md` (minimal — 5-10 lines)
+   - A `design.md` — compact architectural decisions and rationale (why SSE vs WebSocket,
+     why typed client vs raw, why per-request plugin import, etc.). Without this the AI
+     has tasks but no rationale, and will guess wrong on non-obvious decisions.
    - A `tasks.md` (implementation steps)
+   - **Setup instructions** at the top: step-by-step procedure for the target machine
+     (create config.yaml, save proposal/design/tasks, run `/opsx:apply`, reference the portable spec)
 
    Save as: `openspec/exports/<change-name>-openspec.md`
 
-8. **Write the output**
+9. **Write the output**
 
    Save to: `openspec/exports/<change-name>-spec.md`
    Display the full content for review.
@@ -128,4 +180,48 @@ Instead of retyping code, you retype a compact spec. The AI on the sandbox gener
 - In delta mode, add an "Assumes" section so the target AI knows what must exist
 - In the output header, note which changes were included and which were skipped
 
+**Integration rule: adapt, never modify**
+
+The exported feature is a GUEST in the target application. Existing code, patterns,
+and conventions in the target take absolute precedence. The spec must include an
+explicit "Integration Rule" section that states:
+
+- **DO NOT** modify existing files, components, layouts, services, or routing in the target
+- **DO NOT** replace existing patterns with patterns from the source project
+  (e.g., if the target uses a different HttpClient pattern, use theirs)
+- **DO** add new files, new nav links, new routes, new DI registrations
+- **DO** conform to the target's existing code style, naming conventions, and project structure
+- If a task conflicts with existing target code, **stop and notify the user** — the user decides whether to skip, adapt, or redesign
+- If the target already has an equivalent service (e.g., its own markdown renderer,
+  HttpClient wrapper), **use the existing one** instead of creating a new one
+
+When generating the spec, actively identify potential conflict points and add
+explicit "Adapt to target" notes. Common conflicts:
+- Program.cs / DI registration style
+- HttpClient patterns (typed client vs named client vs raw)
+- Layout components (don't restructure MainLayout)
+- CSS approach (isolation vs global vs utility classes)
+- Error handling patterns
+- Navigation structure
+
+**Anti-patterns learned from field use**
+
+These patterns cause the target AI to deviate from the spec even when the spec mentions them:
+
+1. **"Don't use X" warnings get ignored.** AIs skip parenthetical negations buried in
+   bullet lists because their training data overwhelmingly uses the standard pattern.
+   Instead: add a **"Critical Patterns"** section with the exact code snippet to copy.
+   Show the positive pattern, not just the negative warning. E.g., instead of
+   "don't use EndOfStream", show the exact `while ((line = await ReadLineAsync()) != null)` loop.
+
+2. **Layout values that depend on other components break silently.** Magic numbers like
+   `calc(100vh - 48px)` assume a specific AppBar height. Instead: document the dependency
+   explicitly ("48px = MudAppBar Dense height"), suggest using a CSS variable as fallback,
+   and note mobile viewport gotchas (`100vh` vs `100dvh`).
+
+3. **Platform-specific runtime traps need the WHY.** Saying "don't use EndOfStream" is
+   not enough — the AI needs to know WHY (synchronous peek on an async-only stream).
+   When the AI understands the mechanism, it's less likely to reach for an equivalent
+   pattern that has the same problem.
+
 ARGUMENTS:  based on the above

.claude/commands/opsx/extract-feature.md

@@ -105,6 +105,7 @@ Print it, take it to the sandbox, type it in.
 - Mark domain-specific code clearly so the user knows what to adapt vs copy verbatim
 - Keep each step self-contained — the user may take breaks between steps
 - If a feature spans more than ~200 lines of stripped code, warn the user and suggest using `/opsx:export-spec` instead
+- If the feature has UI components, warn that the code recipe does not capture layout context (AppBar height, sidebar width, container sizing). Suggest `/opsx:export-spec` for UI-heavy features — it includes a Target Layout section with ASCII diagram and integration guidance
 - Output must be valid markdown that renders well when printed
 - When in cumulative mode, skip superseded code — always use the latest version of each file
 - In the output header, show which changes were included and which were skipped