@xgent-ai/skills 0.6.0 → 0.7.0

package/skills/phoenix-ui/reference/visualize.md

@@ -0,0 +1,46 @@
+# Visualize: Direction Comps & Asset Production
+
+Load this from [new-work.md](new-work.md) on a comp-led build, when image generation is available (a harness-native tool or the API fallback `phoenix-ui context` reports). A code-led contract skips this file by design, not by drift; do not load it then. PRODUCT.md and DESIGN.md are preconditions. The MODE RULES block concept-seed printed for this surface (COMPS) governs these comps together with this file and wins where they conflict; with no roll this session, read the mode's file named in new-work.md. New-work has already resolved the visual world; this file must not reopen it. A surface-scope structure round that already put three visualized cards before the user (new-work.md, established world) has discharged this round: the locked card's comp is the approved comp, so record the approval and continue at After approval; generate nothing new.
+
+A probe tests composition, narrative, hierarchy, density, focal moment, signature use, and image requirements. It is not a second identity workshop. Keep DESIGN.md's palette, typography direction, material language, component character, imagery stance, and motion grammar fixed.
+
+## Generate three compositional options
+
+The comp round runs inside the build's phase state: `phoenix-ui build-phase start --direction <seed key> --kind <...>` has already run (the roll's output names the command) and its `comps` phase is open before the first comp is generated; a comp rendered before that sits outside the state, and a session resumed from that point has no phases to follow. `phoenix-ui generate-image` refuses to write under `.phoenix-ui/mocks/` until start has run; a harness-native image tool is bound by the same order.
+
+Render three distinct high-fidelity north-star comps of the requested surface, saved under `.phoenix-ui/mocks/` so they survive the session. Comp at the surface's own viewport: portrait at device size for a native app or mobile-first surface, desktop landscape otherwise; a phone screen comped landscape misstates the composition before anything is built against it. Comps are the build thread's own work, never delegated: the thread that writes the prompts holds the direction's full context and has seen every comp when the build starts. Open every image by its workspace-relative path; sandboxed viewers reject absolute paths, and everything under the project root has a relative one. Base the comps on real content and the surface concepts already developed with the user. On an established world, anchor every comp on the real identity: capture a screenshot of a representative existing page and pass it as a reference image (the harness image tool's input image, or `phoenix-ui generate-image --ref`); the prompt leads with the new surface's structure while the reference carries palette, type, and component character, because DESIGN.md words alone drift where a pixel reference does not. Name what the reference contributes and what it must not: chrome, palette, type, and component character carry over; the reference page's own content does not, and a banner, hero, or card lifted verbatim is the reference leaking, not fidelity. Three is the number: one comp invites rubber-stamping; the spread between three surfaces the composition worth building. The chosen card's decision comp is the first of the three: it already renders this direction at full fidelity under this discipline, so generate two more that vary what the first held fixed, from the direction in words rather than with the first comp as an input image (a reference image anchors the layout, and three comps collapse into one composition). How comps two and three vary from the first is the mode's call, in its COMPS rules. A variant that simplifies the first into a tidier version of itself adds no choice to the round. Send all three to the approval point together. Only a round arriving with no decision comp (a degraded roll, an identity-mode page, a direction pinned without the decision round) renders all three here.
+
+- A comp is a designed surface, not a picture of the subject. Lead the prompt with the surface's own structure: the regions this design has, named in order with their scale relationships; a page with no navigation says so instead of inventing one, and an unconventional surface states its unconventional skeleton. A prompt that leads with atmosphere gets a vignette back: the model paints the fish market instead of the fish market's website. How far the world reaches into the page, and what it may carry, is the mode's call, in its COMPS rules. Render the page itself edge to edge: no browser window, address bar, device or desk around it, so prompt it as the page, never as a screenshot of a browser. Self-check every render: if it could hang as a poster, or reads as a photograph with some text on it, it is not a comp; regenerate with the dealt composition's regions named and its parts working in place.
+- The inverse is also a failure: a surface with none of its subject in it. The subject appears as the content the regions hold; the world dresses the frame and never displaces what the frame shows. The deletion usually rides in on the prompt's exclusion list, so exclusions bind invented claims, and a medium ban belongs to the committed imagery stance, never to caution. Before accepting a render, point at the subject; a render that depicts everything about the world and nothing of the subject fails however faithful its atmosphere. Regenerate with the subject's content named region by region.
+- Judge a comp as the shipped screen: the visitor's job must be readable from the image alone. Name the surface's mode from the render with no caption; a render whose mode cannot be read back is art direction without a surface. Regenerate with the visitor's job as the prompt's spine.
+- Commitment is depth, not performance spread across regions. The world enters through one dominant move plus the material, type, and spacing that support it; the remaining regions hold still in that material so the move can be read. A region that simply does its job in the world's grammar carries the direction further than a region performing the concept. The check cuts competition, never content: a quieted region keeps its information and stops performing, and the page still carries its content (a way to navigate, the offer, its supporting copy, an action, a glimpse of what follows) at real reading size (body text near 16px on a 1440px-wide page). That is a list of content, not a layout: where each piece sits is the composition's call. A second element competing with the named focal moment at the same scale means the comp is shouting; with no named focal moment, several regions performing the concept at once is the same shout. Regenerate keeping the strongest move and quieting the rest. Busy is louder, not bolder.
+- When the user shortlisted multiple concepts, spread the three across them.
+- When one direction is committed, vary the structural uncertainty an image can resolve: topology, sequence, density, hierarchy, focal composition, or interaction framing.
+- Show enough beyond the opening moment to prove the concept can govern the whole surface.
+- Do not generate a palette artifact, ask new atmosphere questions, introduce a different type voice, or invent a new motif. If the committed world cannot support the concept, return to the concept shortlist rather than changing the world.
+
+Each comp is a direction test, not a screenshot specification. Core UI text, responsive behavior, accessibility, semantics, and interaction states remain implementation responsibilities.
+
+## One approval point
+
+Show the three together on the decision page (`phoenix-ui serve-question`, one option per comp with the comp as its hero), or in the harness only when it renders images inline; a text-only surface does not count as display. Ask what should carry forward, what feels false to the world, and whether the selected concept should be approved, combined, revised, or rejected. Then stop and wait. A structured simulated user counts as attended and receives the same question.
+
+Do not begin code until the user approves a direction or explicitly delegates the choice. If they delegate, choose using the task brief, PRODUCT.md, and DESIGN.md, and state the evidence. Approval refines the task concept; it does not modify DESIGN.md.
+
+This approval point has no substitute and no skip condition. When the structured question tool errors, fall back to the decision page; only after both fail may you treat the choice as delegated, and a delegated pick is recorded exactly as an approval is and disclosed in your first reply, not your last. The finish reviewer treats comp-round comps with no recorded approval as a material finding; decision comps under `.phoenix-ui/mocks/decision/` are the direction round's hand, not comp-round output, and imply no approval on their own.
+
+After approval, record the choice where tools can find it: the approved comp's path goes in the surface brief, and its prompt sidecar (the image's full file name plus `.json`: `a.png` gets `a.png.json`) gains `"approved": true` (every comp generated through `phoenix-ui generate-image` has one; create it if a native tool didn't). The sidecar travels with the mocks folder, so the approval survives sessions and machines that never see the brief, and it is what `phoenix-ui build-phase advance` reads to close the comps phase. Summarize the composition and the parts of the comp that must not be literalized, return to new-work.md, record the direction contract from the approved concept, and build.
+
+## After approval: the comp becomes a spec
+
+The approved comp is a north star for translation into semantic, responsive, accessible code, never a license to recompose: keeping the palette and mood while redrawing the topology is a second art direction. Do not rasterize core UI text or controls. Do not substitute a different visual driver after approval without asking.
+
+What the comp shows is measured, not remembered. new-work.md section 6 runs the build as phases (`phoenix-ui build-phase`): the spec phase turns the comp into region boxes with sampled palettes (`phoenix-ui comp-spec`), and the medium of every region follows from what the pixels are, never from what feels buildable: a figure, a product object, machinery, any illustration with perspective, shading, or drawing skill in it, and any texture by name (woven cloth, paper grain, fabric, leather, brushed metal) is a `plate` / `image` / `texture` region and ships as a raster; text, controls, chrome, diagrams with countable elements, flat shape systems, and anything that must move, scale, or respond are semantic. Writing "CSS" for a sculpted panel's finish, or a many-vertex `clip-path` for a torn edge, is the quiet deletion of the approved design; the detector's organic-clip-path and buried-raster rules and the hero gate's region scores catch it. Dropping an image-native region is a scope decision the user makes at the approval point, never a silent flattening after it. Generated imagery is a material, not a claim: evidence rules bind assertions, specs, testimonials, and photographs presented as real, never render fidelity.
+
+## Plates and provenance
+
+Every raster region's plate is produced in the plates phase, before any page code, by the shipped asset producer or in the current thread (use `phoenix-ui comp-spec --crop <id>` and save `phoenix-ui comp-spec --plate-prompt <id>` to a prompt file; pass the crop and prompt to the harness image tool, or use `phoenix-ui generate-image --ref <crop.png> --prompt-file <prompt.txt> --out <plate.png> --size <WxH> --quality high`). For isolated cutouts, add `--background transparent` to both the plate-prompt and API generation commands; use native PNG alpha and preserve white paint and clear gaps. Use `--background opaque` for full-frame imagery. Create output directories first and inspect alpha on light and dark grounds. Generation context is part of the asset: after generating any image with any tool, run `<skill-base-dir>/scripts/phoenix-ui embed-prompt <image> --prompt "<prompt>"` with the exact string the tool received (`phoenix-ui generate-image` does this itself), so the intent lives inside the file; `--read` recovers it, `--scan <dir>` lists rasters still missing one. The embedded prompt plus the region's row in the spec is the raster's **provenance**, and every raster the artifact references carries it; a sourced, stock, or pre-existing raster embeds its origin instead. A raster created or replaced later, in a fix batch or a reviewer's rebuild, is produced the same way; a raster a fix abandons is deleted in the same batch.
+
+Convert images with a converter `phoenix-ui context` reported at boot (the IMAGE_TOOLS line); probe only when it reported none, at most once per session, never per image.
+
+Return to [new-work.md](new-work.md) for the direction contract, the phased build, and the finishing pass.

package/skills/phoenix-ui/scripts/ENGINE.json

@@ -0,0 +1,20 @@
+{
+  "schemaVersion": 1,
+  "distribution": "development",
+  "toolVersion": "0.1.0",
+  "npmPackageVersion": "0.7.0",
+  "sourceCommit": "ca775b27b3c772886cb3bce435284d003f07fe37",
+  "sourceTree": "e632a7cdde0e79bef093952dc472bd7ba6d109d5",
+  "sourceState": "dirty",
+  "sourceInputSha256": "2a574581eb3326e33442533dfb6ad7ef284081b308961253cda2497fa1fe6e67",
+  "bundleSchema": 1,
+  "bundleSha256": "95bca755477c6864e11eab1104d2147d0d4c80dca24ec15a058c6af4d96e7c30",
+  "reviewSchema": 1,
+  "engines": {
+    "darwin-arm64": {
+      "asset": "phoenix-ui-darwin-arm64",
+      "sha256": "794e2c95763238021edd26b976be2dab66db4ffd78e9604a567ac8ba87986269",
+      "size": 20924264
+    }
+  }
+}

package/skills/phoenix-ui/scripts/VERSION

@@ -0,0 +1 @@
+0.1.0

package/skills/phoenix-ui/scripts/command-metadata.json

@@ -0,0 +1,98 @@
+{
+  "craft": {
+    "description": "Deprecated compatibility alias for an ordinary Phoenix UI new-work request. It adds no behavior; natural build and redesign requests use the same flow.",
+    "argumentHint": "[feature description]"
+  },
+  "init": {
+    "description": "Sets up a project for Phoenix UI. Runs a multi-round discovery interview when context is missing and writes PRODUCT.md (strategic: users, brand, principles); offers DESIGN.md (visual: colors, typography, components) when code exists; pre-configures live mode; then recommends the best commands to run next. Every other command reads these files before doing work. Use once per project.",
+    "argumentHint": ""
+  },
+  "document": {
+    "description": "Generate a DESIGN.md file that captures the current visual design system. Auto-extracts colors, typography, spacing, radii, and component patterns from the codebase, then asks the user to confirm descriptive language for atmosphere and color character. Follows the Google Stitch DESIGN.md format so the file is tool-compatible. Use when you need a visual design spec an AI agent can follow to stay on-brand.",
+    "argumentHint": ""
+  },
+  "extract": {
+    "description": "Pull reusable patterns, components, and design tokens into the design system. Identifies repeated patterns and consolidates them. Use when you have drift across the codebase and want to bring things back to a consistent system.",
+    "argumentHint": "[target]"
+  },
+  "live": {
+    "description": "Interactive live variant mode. Select elements in the browser, pick a design action, and get AI-generated HTML+CSS variants hot-swapped via HMR. Requires a running dev server. Use when you want to visually experiment with design alternatives in real time.",
+    "argumentHint": ""
+  },
+  "generate": {
+    "description": "Agent-driven live variant generation. Boots live mode, finds the named element on the open page, scrolls the browser to it, and delivers N variants in the requested direction for the user to cycle and accept. Use for requests that name an element and a direction, like 'generate 3 bold variants of the pricing cards', skipping manual element picking.",
+    "argumentHint": "[count] [direction] variants of [element]"
+  },
+  "adapt": {
+    "description": "Adapt designs to work across different screen sizes, devices, contexts, or platforms. Implements breakpoints, fluid layouts, and touch targets. Use when the user mentions responsive design, mobile layouts, breakpoints, viewport adaptation, or cross-device compatibility.",
+    "argumentHint": "[target] [context (mobile, tablet, print...)]"
+  },
+  "animate": {
+    "description": "Review a feature and enhance it with purposeful animations, micro-interactions, and motion effects that improve usability and delight. Use when the user mentions adding animation, transitions, micro-interactions, motion design, hover effects, or making the UI feel more alive.",
+    "argumentHint": "[target]"
+  },
+  "audit": {
+    "description": "Run technical quality checks across accessibility, performance, theming, responsive design, and anti-patterns. Generates a scored report with P0-P3 severity ratings and actionable plan. Use when the user wants an accessibility check, performance audit, or technical quality review.",
+    "argumentHint": "[area (feature, page, component...)]"
+  },
+  "bolder": {
+    "description": "Amplify safe or boring designs to make them more visually interesting and stimulating. Increases impact while maintaining usability. Use when the user says the design looks bland, generic, too safe, lacks personality, or wants more visual impact and character.",
+    "argumentHint": "[target]"
+  },
+  "clarify": {
+    "description": "Improve unclear UX copy, error messages, microcopy, labels, and instructions to make interfaces easier to understand. Use when the user mentions confusing text, unclear labels, bad error messages, hard-to-follow instructions, or wanting better UX writing.",
+    "argumentHint": "[target]"
+  },
+  "colorize": {
+    "description": "Add strategic color to features that are too monochromatic or lack visual interest, making interfaces more engaging and expressive. Use when the user mentions the design looking gray, dull, lacking warmth, needing more color, or wanting a more vibrant or expressive palette.",
+    "argumentHint": "[target]"
+  },
+  "critique": {
+    "description": "Evaluate design from a UX perspective, assessing visual hierarchy, information architecture, emotional resonance, cognitive load, and overall quality with quantitative scoring, persona-based testing, automated anti-pattern detection, and actionable feedback. Use when the user asks to review, critique, evaluate, or give feedback on a design or component.",
+    "argumentHint": "[area (feature, page, component...)]"
+  },
+  "delight": {
+    "description": "Add moments of joy, personality, and unexpected touches that make interfaces memorable and enjoyable to use. Elevates functional to delightful. Use when the user asks to add polish, personality, animations, micro-interactions, delight, or make an interface feel fun or memorable.",
+    "argumentHint": "[target]"
+  },
+  "distill": {
+    "description": "Strip designs to their essence by removing unnecessary complexity. Great design is simple, powerful, and clean. Use when the user asks to simplify, declutter, reduce noise, remove elements, or make a UI cleaner and more focused.",
+    "argumentHint": "[target]"
+  },
+  "harden": {
+    "description": "Make interfaces production-ready: error handling, i18n, text overflow, edge case management, and resilience under real-world data. Use when the user asks to harden, make production-ready, handle edge cases, add error states, or fix overflow and i18n issues.",
+    "argumentHint": "[target]"
+  },
+  "onboard": {
+    "description": "Design onboarding flows, first-run experiences, and empty states that guide new users to value. Covers welcome screens, account setup, progressive disclosure, contextual tooltips, feature announcements, and activation moments. Use when the user mentions onboarding, first-time users, empty states, activation, getting started, new user flows, or the aha moment.",
+    "argumentHint": "[target]"
+  },
+  "layout": {
+    "description": "Improve layout, spacing, and visual rhythm. Fixes monotonous grids, inconsistent spacing, and weak visual hierarchy. Use when the user mentions layout feeling off, spacing issues, visual hierarchy, crowded UI, alignment problems, or wanting better composition.",
+    "argumentHint": "[target]"
+  },
+  "optimize": {
+    "description": "Diagnoses and fixes UI performance across loading speed, rendering, animations, images, and bundle size. Use when the user mentions slow, laggy, janky, performance, bundle size, load time, or wants a faster, smoother experience.",
+    "argumentHint": "[target]"
+  },
+  "overdrive": {
+    "description": "Pushes interfaces past conventional limits with technically ambitious implementations — shaders, spring physics, scroll-driven reveals, 60fps animations. Use when the user wants to wow, impress, go all-out, or make something that feels extraordinary.",
+    "argumentHint": "[target]"
+  },
+  "polish": {
+    "description": "Performs a final quality pass fixing alignment, spacing, consistency, and micro-detail issues before shipping. Use when the user mentions polish, finishing touches, pre-launch review, something looks off, or wants to go from good to great.",
+    "argumentHint": "[target]"
+  },
+  "quieter": {
+    "description": "Tones down visually aggressive or overstimulating designs, reducing intensity while preserving quality. Use when the user mentions too bold, too loud, overwhelming, aggressive, garish, or wants a calmer, more refined aesthetic.",
+    "argumentHint": "[target]"
+  },
+  "shape": {
+    "description": "Plan UX and UI before code. Runs a required multi-round discovery interview, uses visual probes when available, and produces a user-confirmed design brief for implementation.",
+    "argumentHint": "[feature to shape]"
+  },
+  "typeset": {
+    "description": "Improves typography by fixing font choices, hierarchy, sizing, weight, and readability so text feels intentional. Use when the user mentions fonts, type, readability, text hierarchy, sizing looks off, or wants more polished, intentional typography.",
+    "argumentHint": "[target]"
+  }
+}

package/skills/phoenix-ui/scripts/data/catalog/composition-ingredients.json

@@ -0,0 +1,256 @@
+{
+  "schemaVersion": 2,
+  "catalogVersion": "phoenix-2026-01",
+  "authoringStatus": "draft",
+  "qualityBar": {
+    "principle": "A composition specifies relationships among information, attention, controls, and adaptation while leaving visual identity to project direction. Its structure must fit a concrete task with actual state, accessible actions, and honest implementation boundaries."
+  },
+  "families": [
+    {
+      "id": "phoenix-composition-persuade",
+      "label": "Informed decisions",
+      "description": "Original arrangements connecting an offer, its evidence or fit, complete conditions, and the next decision."
+    },
+    {
+      "id": "phoenix-composition-operate",
+      "label": "Scoped work",
+      "description": "Original arrangements preserving object scope, review context, explicit commitment, and concrete results."
+    },
+    {
+      "id": "phoenix-composition-read",
+      "label": "Located understanding",
+      "description": "Original arrangements connecting question maps or corresponding sections to readable explanation and evidence."
+    },
+    {
+      "id": "phoenix-composition-experience",
+      "label": "Revisable participation",
+      "description": "Original arrangements supporting optional exploration or accessible co-authoring with visible context and return."
+    }
+  ],
+  "compositions": [
+    {
+      "id": "phoenix-persuade-claim-proof-decision",
+      "familyId": "phoenix-composition-persuade",
+      "surface": "persuade",
+      "form": "A claim-to-decision view, the primary promise leads into comparable evidence and then one complete decision region.",
+      "lineage": "Original composition connecting a purchase claim to its support and a fully informed next step.",
+      "tags": [
+        "claim-support",
+        "comparable-evidence",
+        "decision-region"
+      ],
+      "grammar": [
+        "Staging/hierarchy: Give one primary claim highest rank; use readable headings for supporting evidence and decision detail.",
+        "Sequence/attention: Move from claim to support to conditions and decision; keep qualifications beside the claims they limit.",
+        "Controls/state: Put the primary next step after the complete offer; show unavailable or uncertain states explicitly.",
+        "Adaptation: Stack evidence by criterion on small screens; retain order without sticky controls hiding required content."
+      ],
+      "spark": "Let readers connect the offer, the reason to trust it, and the consequence of choosing it in one clear pass through the page, with qualifications still readable.",
+      "webLeverage": "Use semantic sections, comparable tables or lists, and an explicit decision form without imposing palette or typeface.",
+      "applicability": "适用于具备真实证据和明确条件的产品介绍、订阅选择或服务报价单页。",
+      "thesis": "让主张、依据与决定形成连续空间关系，并保持条件可读。",
+      "provenance": "Original Phoenix catalog authoring text proposal for this local catalog; no external model, fixture copying, project acceptance, or implemented interface is asserted.",
+      "source": {
+        "kind": "original",
+        "title": "Phoenix original composition: Claim, proof, decision",
+        "license": "Apache-2.0"
+      }
+    },
+    {
+      "id": "phoenix-persuade-fit-cost-next-step",
+      "familyId": "phoenix-composition-persuade",
+      "surface": "persuade",
+      "form": "A fit-to-next-step flow, requirements remain visible beside the resulting option, complete cost, and an editable final summary.",
+      "lineage": "Original composition retaining needs, price assumptions, and the final decision across guided offer selection.",
+      "tags": [
+        "visible-requirements",
+        "cost-assumptions",
+        "editable-summary"
+      ],
+      "grammar": [
+        "Staging/hierarchy: Give the current question primary position; maintain a compact requirements summary beside the result.",
+        "Sequence/attention: Move from needs to option and cost to the next step; expose the assumptions explaining recommendations.",
+        "Controls/state: Provide back and edit actions; distinguish an estimate from a committed order and disclose incomplete fit.",
+        "Adaptation: Use one narrow-screen column; retain answers and restore focus after editing earlier requirements."
+      ],
+      "spark": "Hold the reason for a recommendation together with its cost, so returning to a requirement changes a visible decision rather than restarting a hidden sales funnel.",
+      "webLeverage": "Use grouped forms, named step regions, and an accessible editable summary whose updates do not steal focus.",
+      "applicability": "适用于明确需求推荐套餐的选择流程，系统能解释推荐并完整计算成本。",
+      "thesis": "让需求、依据和成本连续可见，支持修改与检查结果。",
+      "provenance": "Original Phoenix catalog authoring text proposal for this local catalog; no external model, fixture copying, project acceptance, or implemented interface is asserted.",
+      "source": {
+        "kind": "original",
+        "title": "Phoenix original composition: Fit, cost, next step",
+        "license": "Apache-2.0"
+      }
+    },
+    {
+      "id": "phoenix-operate-record-detail-action",
+      "familyId": "phoenix-composition-operate",
+      "surface": "operate",
+      "form": "A record-to-action workspace, a stable collection opens contextual detail and a scoped action while the active record remains identifiable.",
+      "lineage": "Original composition giving operational selection, inspection, and action one explicit object scope.",
+      "tags": [
+        "stable-collection",
+        "contextual-detail",
+        "scoped-action"
+      ],
+      "grammar": [
+        "Staging/hierarchy: Rank collection location, record identity, and action scope clearly; subordinate detail to the current task.",
+        "Sequence/attention: Select a record, inspect detail, then act; preserve collection filters and return location throughout.",
+        "Controls/state: Separate loading, stale, edited, committed, and failed states; name actions and keep cancellation explicit.",
+        "Adaptation: Replace adjacent regions with labeled detail on small screens; return focus to the originating record."
+      ],
+      "spark": "Keep one object unmistakable through inspection and action, then return the operator to the same filtered collection with the result of their work clearly stated.",
+      "webLeverage": "Use semantic collection and detail regions, stable identifiers, scoped forms, and an explicit focus return target.",
+      "applicability": "适用于记录管理 Portal、库存或工单后台，可保持列表筛选并提供清晰对象详情。",
+      "thesis": "持续联系列表位置、活动对象和操作范围，降低错误对象操作。",
+      "provenance": "Original Phoenix catalog authoring text proposal for this local catalog; no external model, fixture copying, project acceptance, or implemented interface is asserted.",
+      "source": {
+        "kind": "original",
+        "title": "Phoenix original composition: Record, detail, action",
+        "license": "Apache-2.0"
+      }
+    },
+    {
+      "id": "phoenix-operate-before-after-commit",
+      "familyId": "phoenix-composition-operate",
+      "surface": "operate",
+      "form": "A before-and-after commitment flow, proposed differences and affected scope are reviewed before a separate explicit commit and result.",
+      "lineage": "Original composition separating review of consequential configuration or bulk change from commitment.",
+      "tags": [
+        "proposal-difference",
+        "affected-scope",
+        "separate-commit"
+      ],
+      "grammar": [
+        "Staging/hierarchy: Prioritize proposed differences and scope; put commitment after review rather than above its evidence.",
+        "Sequence/attention: Inspect old and proposed values, examine consequences, then commit; keep unchanged context available.",
+        "Controls/state: Invalidate stale previews and distinguish partial failure; name consequences and promise only supported undo.",
+        "Adaptation: Stack labeled before/after values on small screens; place consequence summary beside the commit control."
+      ],
+      "spark": "Make commitment deliberate through a specific reviewed difference and scope; the subsequent result identifies what succeeded and what still needs attention rather than implying universal success.",
+      "webLeverage": "Use labeled comparisons, scoped confirmation forms, and accessible result lists with specific failure or retry detail.",
+      "applicability": "适用于配置审批、权限调整或批量修改，可生成真实预览并返回具体提交结果。",
+      "thesis": "真实差异与影响审查之后单独提交，并诚实展示失败和恢复边界。",
+      "provenance": "Original Phoenix catalog authoring text proposal for this local catalog; no external model, fixture copying, project acceptance, or implemented interface is asserted.",
+      "source": {
+        "kind": "original",
+        "title": "Phoenix original composition: Before, after, commit",
+        "license": "Apache-2.0"
+      }
+    },
+    {
+      "id": "phoenix-read-overview-body-evidence",
+      "familyId": "phoenix-composition-read",
+      "surface": "read",
+      "form": "An overview-to-evidence reading view, a descriptive section map leads into a stable text column with support connected to each argument.",
+      "lineage": "Original composition joining a reader question map to detailed explanation and inspectable support.",
+      "tags": [
+        "section-map",
+        "stable-text",
+        "connected-evidence"
+      ],
+      "grammar": [
+        "Staging/hierarchy: Give title, section promises, body, and references distinct readable roles; keep the reading column stable.",
+        "Sequence/attention: Read overview before detail; connect support to its passage and return to the same reading location.",
+        "Controls/state: Provide contents and note-return links; keep required content readable without optional disclosures.",
+        "Adaptation: Move side material into small-screen flow; preserve heading order and usability at enlarged text sizes."
+      ],
+      "spark": "Serve both quick question lookup and sustained reading: locate a useful section, inspect its detail, and verify supporting evidence without being displaced from the argument.",
+      "webLeverage": "Use semantic headings, contents navigation, stable fragments, and accessible reference backlinks without imposing visual identity.",
+      "applicability": "适用于技术指南、政策说明和有真实引用的长篇知识文章。",
+      "thesis": "连接问题地图、正文与局部证据，使定位与持续阅读共存。",
+      "provenance": "Original Phoenix catalog authoring text proposal for this local catalog; no external model, fixture copying, project acceptance, or implemented interface is asserted.",
+      "source": {
+        "kind": "original",
+        "title": "Phoenix original composition: Overview, body, evidence",
+        "license": "Apache-2.0"
+      }
+    },
+    {
+      "id": "phoenix-read-parallel-explanation",
+      "familyId": "phoenix-composition-read",
+      "surface": "read",
+      "form": "A parallel explanation region, corresponding source and interpretation remain aligned with explicit labels and an optional combined reading view.",
+      "lineage": "Original composition retaining corresponding statements and consequences in migration or specialist explanations.",
+      "tags": [
+        "corresponding-sections",
+        "explicit-labels",
+        "combined-view"
+      ],
+      "grammar": [
+        "Staging/hierarchy: Give paired sections equal readable roles; distinguish commentary from source through explicit labels.",
+        "Sequence/attention: Inspect one corresponding pair at a time; connect its difference to practical meaning before advancing.",
+        "Controls/state: Switch paired and combined views explicitly; preserve active section, focus, and selection context.",
+        "Adaptation: Stack corresponding labeled sections on small screens; retain anchors without forced synchronized scrolling."
+      ],
+      "spark": "Explain a relationship rather than merely placing text side by side: each corresponding pair identifies the interpreted content and why its difference matters to the reader.",
+      "webLeverage": "Use named sections, stable anchors, and accessible view controls preserving focus and source/interpretation labels.",
+      "applicability": "适用于 API 迁移解释、规范解读或版本对照，原文与解释能按章节准确对应。",
+      "thesis": "用明确对应关系帮助理解，避免并排布局制造位置或来源混淆。",
+      "provenance": "Original Phoenix catalog authoring text proposal for this local catalog; no external model, fixture copying, project acceptance, or implemented interface is asserted.",
+      "source": {
+        "kind": "original",
+        "title": "Phoenix original composition: Parallel explanation",
+        "license": "Apache-2.0"
+      }
+    },
+    {
+      "id": "phoenix-experience-choose-explore-return",
+      "familyId": "phoenix-composition-experience",
+      "surface": "experience",
+      "form": "A choose-and-return exploration flow, a compact overview opens bounded branches and restores the visitor to the same identifiable choice.",
+      "lineage": "Original composition arranging an optional choice point, bounded detail branch, and reliable return.",
+      "tags": [
+        "choice-overview",
+        "bounded-branch",
+        "reliable-return"
+      ],
+      "grammar": [
+        "Staging/hierarchy: Give current choice or branch a clear primary heading; preserve its relationship to the compact overview.",
+        "Sequence/attention: Choose a topic, inspect bounded detail, then return or choose another; never advance automatically.",
+        "Controls/state: Provide named back and restart; distinguish visited from completed and retain the originating choice.",
+        "Adaptation: Use an ordered small-screen overview; restore focus and context after branches without requiring motion."
+      ],
+      "spark": "Support curiosity without lost orientation: every branch has a clear extent, an identifiable starting choice, and a return path restoring the overview the visitor left.",
+      "webLeverage": "Use semantic navigation, stable routes or fragments, named detail headings, and accessible focus restoration on return.",
+      "applicability": "适用于互动展览、产品细节探索或可选分支教学，内容有明确起点和有限分支。",
+      "thesis": "让探索由用户选择推动，以可见起点和可靠返回支持自由路线。",
+      "provenance": "Original Phoenix catalog authoring text proposal for this local catalog; no external model, fixture copying, project acceptance, or implemented interface is asserted.",
+      "source": {
+        "kind": "original",
+        "title": "Phoenix original composition: Choose, explore, return",
+        "license": "Apache-2.0"
+      }
+    },
+    {
+      "id": "phoenix-experience-arrange-preview-revise",
+      "familyId": "phoenix-composition-experience",
+      "surface": "experience",
+      "form": "An arrange-and-preview workspace, ordered contributions stay connected to the current result while participants inspect and revise their sequence.",
+      "lineage": "Original composition linking each editable contribution to its place in a visible ordered result.",
+      "tags": [
+        "ordered-editor",
+        "current-preview",
+        "inspectable-revision"
+      ],
+      "grammar": [
+        "Staging/hierarchy: Separate editable order and current preview clearly; label position and the affected contribution.",
+        "Sequence/attention: Inspect, revise, then inspect the changed preview; preserve the selected contribution through the sequence.",
+        "Controls/state: Provide move and remove controls and only supported undo; expose rather than hide concurrent conflicts.",
+        "Adaptation: Stack editor and preview on small screens; retain focus after moves and support revision without dragging."
+      ],
+      "spark": "Make a developing result understandable through its pieces: participants see where a contribution sits, change it with accessible controls, and inspect the consequence in the preview.",
+      "webLeverage": "Use ordered lists, named revision controls, position announcements, and a preview that does not replace editor focus.",
+      "applicability": "适用于共创提纲、故事排序或步骤编排，结果能由当前有序内容真实生成。",
+      "thesis": "同时展示贡献、顺序和结果，支持可理解且可访问的修改。",
+      "provenance": "Original Phoenix catalog authoring text proposal for this local catalog; no external model, fixture copying, project acceptance, or implemented interface is asserted.",
+      "source": {
+        "kind": "original",
+        "title": "Phoenix original composition: Arrange, preview, revise",
+        "license": "Apache-2.0"
+      }
+    }
+  ]
+}

package/skills/phoenix-ui/scripts/data/catalog/composition-reviews.json

@@ -0,0 +1,103 @@
+{
+  "schemaVersion": 2,
+  "catalogVersion": "phoenix-2026-01",
+  "authoringStatus": "draft",
+  "reviews": {
+    "phoenix-persuade-claim-proof-decision": {
+      "status": "approved",
+      "reviewedBy": "Phoenix catalog authoring",
+      "reviewedAt": "2026-10-09T01:33:08.485Z",
+      "formHash": "df79966a9273",
+      "rating": 2,
+      "breadth": "general",
+      "allowedModes": [
+        "persuade"
+      ],
+      "note": "approved 仅表示可供建议的原创作者策展条目；目录仍为 draft，未获用户接受且运行时验收尚未完成，不是项目已接受的设计规范，也不代表实拍、实现或运行时验收。"
+    },
+    "phoenix-persuade-fit-cost-next-step": {
+      "status": "approved",
+      "reviewedBy": "Phoenix catalog authoring",
+      "reviewedAt": "2026-10-09T01:33:08.485Z",
+      "formHash": "83ffb571e6c8",
+      "rating": 2,
+      "breadth": "general",
+      "allowedModes": [
+        "persuade"
+      ],
+      "note": "approved 仅表示可供建议的原创作者策展条目；目录仍为 draft，未获用户接受且运行时验收尚未完成，不是项目已接受的设计规范，也不代表实拍、实现或运行时验收。"
+    },
+    "phoenix-operate-record-detail-action": {
+      "status": "approved",
+      "reviewedBy": "Phoenix catalog authoring",
+      "reviewedAt": "2026-10-09T01:33:08.485Z",
+      "formHash": "cde2ff82425d",
+      "rating": 2,
+      "breadth": "general",
+      "allowedModes": [
+        "operate"
+      ],
+      "note": "approved 仅表示可供建议的原创作者策展条目；目录仍为 draft，未获用户接受且运行时验收尚未完成，不是项目已接受的设计规范，也不代表实拍、实现或运行时验收。"
+    },
+    "phoenix-operate-before-after-commit": {
+      "status": "approved",
+      "reviewedBy": "Phoenix catalog authoring",
+      "reviewedAt": "2026-10-09T01:33:08.485Z",
+      "formHash": "a7af085294d8",
+      "rating": 2,
+      "breadth": "general",
+      "allowedModes": [
+        "operate"
+      ],
+      "note": "approved 仅表示可供建议的原创作者策展条目；目录仍为 draft，未获用户接受且运行时验收尚未完成，不是项目已接受的设计规范，也不代表实拍、实现或运行时验收。"
+    },
+    "phoenix-read-overview-body-evidence": {
+      "status": "approved",
+      "reviewedBy": "Phoenix catalog authoring",
+      "reviewedAt": "2026-10-09T01:33:08.485Z",
+      "formHash": "18786987507f",
+      "rating": 2,
+      "breadth": "general",
+      "allowedModes": [
+        "read"
+      ],
+      "note": "approved 仅表示可供建议的原创作者策展条目；目录仍为 draft，未获用户接受且运行时验收尚未完成，不是项目已接受的设计规范，也不代表实拍、实现或运行时验收。"
+    },
+    "phoenix-read-parallel-explanation": {
+      "status": "approved",
+      "reviewedBy": "Phoenix catalog authoring",
+      "reviewedAt": "2026-10-09T01:33:08.485Z",
+      "formHash": "cc4c8b952bce",
+      "rating": 2,
+      "breadth": "general",
+      "allowedModes": [
+        "read"
+      ],
+      "note": "approved 仅表示可供建议的原创作者策展条目；目录仍为 draft，未获用户接受且运行时验收尚未完成，不是项目已接受的设计规范，也不代表实拍、实现或运行时验收。"
+    },
+    "phoenix-experience-choose-explore-return": {
+      "status": "approved",
+      "reviewedBy": "Phoenix catalog authoring",
+      "reviewedAt": "2026-10-09T01:33:08.485Z",
+      "formHash": "0e79aa68d2dc",
+      "rating": 2,
+      "breadth": "general",
+      "allowedModes": [
+        "experience"
+      ],
+      "note": "approved 仅表示可供建议的原创作者策展条目；目录仍为 draft，未获用户接受且运行时验收尚未完成，不是项目已接受的设计规范，也不代表实拍、实现或运行时验收。"
+    },
+    "phoenix-experience-arrange-preview-revise": {
+      "status": "approved",
+      "reviewedBy": "Phoenix catalog authoring",
+      "reviewedAt": "2026-10-09T01:33:08.485Z",
+      "formHash": "553630c4e5fd",
+      "rating": 2,
+      "breadth": "general",
+      "allowedModes": [
+        "experience"
+      ],
+      "note": "approved 仅表示可供建议的原创作者策展条目；目录仍为 draft，未获用户接受且运行时验收尚未完成，不是项目已接受的设计规范，也不代表实拍、实现或运行时验收。"
+    }
+  }
+}