yugoo-design 0.1.2 → 0.2.0

package/payload/desktop-preparation/studio-authoring-template/authoring/studio-creators/source/packages/skills-web-app/bundles/role_access/validation.yaml

@@ -0,0 +1,147 @@
+# Declarative rules enforce material catalogs, required fields, and order
+# references. Rich cross-collection permission semantics remain Producer
+# self-checks in SKILL.md.
+skill: role_access
+
+rules:
+  # Rich permission-quality checks remain Producer self-checks in SKILL.md.
+  # Optional inheritance is structural, not a natural-language ACL evaluator.
+  - id: inheritance_ids_match_keys
+    scope: [state, completion]
+    code: role_access.invalid_inheritance_id
+    message: "inheritance mapping key {key} must equal inheritance.id"
+    repair_hint: "Preserve each stable edge ID and keep its map key identical."
+    check: { map_keys_match_field: { map: inheritances, field: id } }
+
+  - id: inheritance_title
+    scope: [state, completion]
+    code: role_access.incomplete_inheritance
+    message: "inheritance {key}: title is empty"
+    repair_hint: "Give the inheritance edge a readable label."
+    check: { for_each_in_map: inheritances, non_empty_string: title }
+
+  - id: inheritance_source
+    scope: [state, completion]
+    code: role_access.invalid_inheritance_endpoint
+    message: "inheritance {key}: source must be an existing child role"
+    repair_hint: "Connect existing role IDs; do not invent a role to repair an edge."
+    check: { for_each_in_map: inheritances, member_of_map: { value: source, map: roles } }
+
+  - id: inheritance_target
+    scope: [state, completion]
+    code: role_access.invalid_inheritance_endpoint
+    message: "inheritance {key}: target must be an existing parent role"
+    repair_hint: "Connect existing role IDs; do not invent a role to repair an edge."
+    check: { for_each_in_map: inheritances, member_of_map: { value: target, map: roles } }
+
+  - id: inheritance_acyclic
+    scope: [state, completion]
+    code: role_access.cyclic_inheritance
+    message: "inheritance {key}: self-inheritance or a role cycle is not allowed"
+    repair_hint: "Remove the invalid edge while preserving grounded roles and policies."
+    check: { acyclic_record_edges: { map: inheritances, source: source, target: target } }
+
+  - id: inheritance_single_parent
+    scope: [state, completion]
+    code: role_access.multiple_parents
+    message: "inheritance {key}: a role must have at most one parent edge"
+    repair_hint: "Keep one evidenced parent, or report that the product needs an unsupported multi-parent model."
+    check: { single_parent_record_edges: { map: inheritances, source: source, target: target } }
+
+  - id: empty_roles
+    scope: [state]
+    code: role_access.empty_roles
+    message: "At least one role is required."
+    repair_hint: "Add the smallest grounded set of distinct permission roles."
+    check: { non_empty_map: roles }
+
+  - id: empty_policies
+    scope: [state]
+    code: role_access.empty_policies
+    message: "At least one permission decision is required."
+    repair_hint: "Add the material allow or explicit deny decisions owned by the roles."
+    check: { non_empty_map: policies }
+
+  - id: role_assignment_rule
+    scope: [state, completion]
+    code: role_access.incomplete_role
+    message: "role {key}: `assignment_rule` is empty"
+    repair_hint: "Explain who receives this role and when."
+    check: { for_each_in_map: roles, non_empty_string: assignment_rule }
+
+  - id: policy_role_ref
+    scope: [state, completion]
+    code: role_access.incomplete_policy
+    message: "policy {key}: `role_ref` is empty"
+    repair_hint: "Assign the policy to exactly one existing role."
+    check: { for_each_in_map: policies, non_empty_string: role_ref }
+
+  - id: policy_capability
+    scope: [state, completion]
+    code: role_access.incomplete_policy
+    message: "policy {key}: `capability` is empty"
+    repair_hint: "Name one user-visible operation for this permission decision."
+    check: { for_each_in_map: policies, non_empty_string: capability }
+
+  - id: policy_role_exists
+    scope: [state, completion]
+    code: role_access.invalid_policy_role
+    message: "policy {key}: role_ref must reference an existing role"
+    repair_hint: "Preserve the policy owner; resolve or remove a dangling reference explicitly."
+    check: { for_each_in_map: policies, member_of_map: { value: role_ref, map: roles } }
+
+  - id: role_order_refs
+    scope: [state, completion]
+    code: role_access.invalid_role_order
+    message: "role_order references missing role {key}"
+    repair_hint: "Keep each live role ID exactly once in role_order."
+    check: { order_refs_map: { order: role_order, map: roles } }
+
+  - id: role_order_empty
+    scope: [state, completion]
+    code: role_access.invalid_role_order
+    message: "role_order is empty"
+    repair_hint: "Keep each live role ID exactly once in role_order."
+    check: { non_empty_list: role_order }
+
+  - id: role_ids_match_keys
+    scope: [state, completion]
+    code: role_access.invalid_role_id
+    message: "role mapping key {key} must equal role.id"
+    repair_hint: "Keep the role mapping key equal to the record's stable id."
+    check: { map_keys_match_field: { map: roles, field: id } }
+
+  - id: role_order_exact
+    scope: [state, completion]
+    code: role_access.invalid_role_order
+    message: "role_order must contain role {key} exactly once"
+    repair_hint: "Keep each live role ID exactly once in role_order."
+    check: { order_exactly_covers_map: { order: role_order, map: roles } }
+
+  - id: policy_order_refs
+    scope: [state, completion]
+    code: role_access.invalid_policy_order
+    message: "policy_order references missing policy {key}"
+    repair_hint: "Keep each live policy ID exactly once in policy_order."
+    check: { order_refs_map: { order: policy_order, map: policies } }
+
+  - id: policy_order_empty
+    scope: [state, completion]
+    code: role_access.invalid_policy_order
+    message: "policy_order is empty"
+    repair_hint: "Keep each live policy ID exactly once in policy_order."
+    check: { non_empty_list: policy_order }
+
+  - id: policy_ids_match_keys
+    scope: [state, completion]
+    code: role_access.invalid_policy_id
+    message: "policy mapping key {key} must equal policy.id"
+    repair_hint: "Keep the policy mapping key equal to the record's stable id."
+    check: { map_keys_match_field: { map: policies, field: id } }
+
+  - id: policy_order_exact
+    scope: [state, completion]
+    code: role_access.invalid_policy_order
+    message: "policy_order must contain policy {key} exactly once"
+    repair_hint: "Keep each live policy ID exactly once in policy_order."
+    check: { order_exactly_covers_map: { order: policy_order, map: policies } }

package/payload/desktop-preparation/studio-authoring-template/authoring/studio-creators/source/packages/skills-web-app/bundles/smart_questions/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: smart_questions
+description: |-
+  - **Capability**: maintain coherent product background and evolving context through editable questions and answers.
+  - **Resolves**: understanding of users, needs, value, scenarios and boundaries, plus relevant context not owned by another design facet.
+  - **Candidate when**: exploring requirements, reconstructing product background, or clarifying context necessary for the current result.
+  - **Do not infer**: missing details or low scores require a questionnaire; do not replace an authorized deliverable with questions.
+  - **Output**: the existing `smart_questions` panel, not a technical inventory or a personal profile.
+---
+
+# Smart Questions
+
+## Purpose: product understanding that evolves
+
+Maintain a coherent account of who the product serves, the problem in their
+situation, the outcome it enables, and its scope. This overall product background
+is a first-class responsibility of this Bundle, not information left over after
+other Bundles run.
+
+Continue maintaining context as the design develops: material constraints,
+assumptions and user decisions that affect that understanding but do not have a
+better home in another facet. Prefer revising the relevant existing card over
+adding a new one for every discovery. These are two responsibilities within the
+same question panel, not new record types, UI sections or workflow stages.
+
+Detailed feature catalogs, flows, data definitions, permissions and testable
+business rules belong to their respective Bundles. Their implications for the
+product's audience, value or boundary can belong here; do not duplicate their
+specifications. For example, how usage is charged is a business rule, while
+whether the product serves occasional users or a paid professional workflow may
+be important product background. A stray technical fact does not qualify merely
+because no other Bundle has recorded it.
+
+## Shared method for design and reconstruction
+
+Read [the shared output contract](reference/artifact-contract.md) for these field meanings, examples and checks; it is used by both ordinary design and reconstruction.
+
+## Interaction: useful to this person now
+
+Choose how to resolve uncertainty before turning it into a question:
+
+- An observable fact: inspect the relevant available evidence, rather than ask
+  the user to reconstruct it from memory. External research remains subject to
+  its own scope and handoff; do not silently start another Bundle.
+- A product decision the user can make now: explain the situation, the desired
+  outcome and the consequential tradeoff. Ask about that coherent choice, not
+  every setting that could eventually implement it.
+- A choice that needs experience: identify what a concrete example or proposed
+  prototype would help the user judge. For example, seeing a representative
+  result can reveal whether its information is useful; asking for field counts
+  cannot. Offer the smallest useful demonstration within the authorized work,
+  or describe the next step without executing another Bundle here.
+- A detail unnecessary for the current result: retain the uncertainty and
+  proceed within the agreed scope; do not turn it into a prerequisite.
+
+These are reasoning choices, not new question types or persisted statuses.
+The question panel remains the interaction surface: put a concise proposal,
+its useful context and the decision to make in the card's `prompt`, with
+appropriate `choices` or free-text input. Do not put the proposed answer into
+the user's `answer` or use `detail` as a substitute for visible question text.
+In forward design, leave new `detail` empty unless it preserves an actual
+user-supplied explanation or a faithful summary of explicit user evidence.
+Put your proposed scope, rationale, examples and unresolved questions in
+`prompt`, not in user-response fields. Your earlier proposal, a Producer brief,
+and another Agent's summary do not establish that the user said or confirmed
+something; trace prefilled answers to direct user input or saved user edits.
+Do not replace the panel with a chat-only interview or a native Ask Question.
+If judging a real prototype requires another Bundle, the card can offer that
+next step or deferral; it does not generate or launch the prototype itself.
+When showing a proposal, ask about its usefulness in the user's situation,
+not just whether they like it. A hypothetical preference is not evidence of
+successful use. Preserve an explicit "first a personal version" boundary;
+future collaboration questions need not be settled to explore that version.
+
+Use explicit Host-supplied collaboration preferences and the current brief to
+calibrate terminology, explanation depth and answer format. A domain expert may
+need technical tradeoffs explained; an exploratory user may need examples.
+Treat inferred expertise or mood as tentative and adapt when corrected. The
+collaborator is not necessarily the product's target user. Personal traits are
+not product evidence: do not store them in Design Files or GROUND, build a user
+profile, or access a host-specific preference file. Long-term preference storage
+belongs to the Host under its existing authorization rules.
+
+For explicit exploration, a focused two-to-five-question round is often useful.
+For an already requested deliverable, prefer one to three necessary questions;
+one is enough, and none is better if a safe reversible provisional choice serves
+the request. These are interaction guidelines, not a cap on the total persisted
+background or the number of source-backed reconstruction cards.
+
+Explain the concrete consequence briefly, using product language rather than
+internal IDs or implementation jargon. Each question should address one coherent
+topic. Use single choice for one priority or mutually exclusive alternatives;
+multi-select only for compatible choices, not as a substitute for ranking.
+Recommend a minimal coherent proposal rather than every option. Use free text
+when choices cannot usefully express the answer.
+
+When the user wants a result, offer explicit reversible defaults rather than
+forcing premature decisions. Do not record a recommendation as their answer.
+Ask the smallest necessary question when a consequential decision has no safe
+provisional option; explain why, or propose a narrower scope without silently
+changing agreed scope. Never ask about Host-managed deployment, credentials,
+hosting or infrastructure tuning. Technical decisions remain product questions
+only when their user-visible consequences actually require user judgment.
+Application-type choices must respect the supplied platform environment.
+
+Offer "other", "not sure, advise me", or "simplify first; decide after the
+prototype" where meaningful. Preserve the user's words through existing fields.
+Deferral is a valid instruction about proceeding, not approval of unknown
+details. Do not rephrase rejected/deferred questions after a mere round or
+revision change. Revisit only when the user returns to the decision, material
+new evidence changes its impact, or a newly requested result genuinely needs it;
+explain what changed. Fixed login/storage defaults alone never justify a round.
+
+## Eliciting a concrete situation without a story template
+
+When the current result is hard for the user to judge, invite one recognizable
+situation: what they were trying to achieve, what made it difficult, and what
+would count as a useful result. These are possible angles, not a required
+three-question interview. For example, “最近一次整理文献时，什么事情最费劲？
+如果这个平台能帮上忙，你希望最后得到什么？” is a neutral expression prompt,
+not a request to learn a user-story format or invent an ideal workflow.
+
+First reuse concrete situations already in the conversation and saved answers.
+Do not create a second card just to restate them. Ask only the uncertainty that
+matters to the authorized design; do not ask again because functions have been
+generated or optional details remain empty. A declined or deferred situation
+question follows the existing revisit rules above.
+
+An AI example belongs in the visible prompt and must be labelled hypothetical.
+It is not an answer, confirmation, or evidence that the proposed function is
+needed. Actual user expression can support subsequent function design and a
+derived experience without creating a story entity here. A future optional
+story Bundle may refer to these same answers; this question panel does not
+claim ownership of formal story management or duplicate its records.
+
+## Evidence: different sources, the same product questions
+
+### Forward design
+
+Use user statements and established Design evidence without asking again.
+Update an existing relevant card when a user changes its answer. Do not create
+a self-answered duplicate just to copy another artifact or log a chat statement.
+Maintain shared product facts through the existing owning paths; the Producer
+does not gain authority to write another Bundle or GROUND from this instruction.
+Preserve existing answers, including the fixed cards' initialized values;
+preserving a value does not newly confirm it. For a new unanswered dynamic
+question, leave `answer` empty until the user supplies or adopts an answer.
+A recommendation for the deliverable belongs in the question's proposal, not
+in that empty answer. Follow the fixed-card initialization contract below when
+creating a panel; do not clear its defaults because no new confirmation occurred.
+In both cases, describe the actual basis of a value rather than equating a
+non-empty answer with user approval.
+
+### Reconstruction
+
+Read [the shared output contract](reference/artifact-contract.md) for these field meanings, examples and checks; it is used by both ordinary design and reconstruction.
+
+## Persistence and close-out
+
+The active Bundle executor (main Agent or Producer, selected by execution.mode) maintains
+`smart_questions/smart_questions.json` through its existing project-scoped
+`list`, `read_design_file`, `write` and `edit` tools. Preserve complete state, stable card IDs,
+untouched answers/details, rejected records, attachments and fixed definitions.
+Merge supporting context into its existing topic when appropriate, without
+discarding user information. Add new dynamic cards only for new material topics;
+explicitly assign their round and its independent introduction as described in
+the shared output contract. The executor, not a presumed automatic write hook,
+owns that assignment. Do not relabel every old card to reorder history
+or impose a new questionnaire lifecycle. A panel save already persists edits;
+do not rewrite unchanged answers merely to advance conversation.
+
+For each new dynamic round, author nonempty `rounds["<round>"].title` and
+`description` separately from every question's `prompt`. Use a short, specific
+topic title (Chinese: preferably at most 12 characters; English: a short phrase),
+not the first question, a numbered label or a paragraph. This is writing guidance,
+not a hard length limit or permission to truncate saved text. Explain the round's
+purpose and useful context in `description`; each card still carries the full
+concrete question, proposal and decision context that makes it answerable.
+Round introductions are neither answers nor user confirmation. Preserve existing
+round metadata when revising answers. Old files without metadata remain readable;
+do not derive or backfill round copy from their first question, rewrite historical
+prompts, or create a round merely to populate these optional fields.
+
+When presenting actual new questions awaiting input, validate with
+`design_validate({outcome:"pause"})`, repair diagnostics and publish with
+`design_publish({action:"handoff"})`. An unanswered panel awaits the user.
+When saved answers or explicit deferral leave no current necessary question,
+validate the final state and complete the engagement with
+`design_publish({action:"complete"})`; do not reopen a gate just because a detail
+remains unknown. Reconstruction validates and publishes with action complete
+for unified user review, without an ordinary unanswered-panel pause. The main
+Agent may continue only work already authorized; no new receipt authority follows.
+
+Report actual clarification, not answer counts. Non-empty answers, source
+prefill or "not sure" alone do not increase U/S/T or imply confirmation.
+Material user answers can clarify U; concrete scope, workflow or observable
+behavior can support S/T under the existing Host rubric. Explicit scope
+reduction may add evidence while other details remain unknown.
+
+## Fixed-card contract
+
+Read [the shared output contract](reference/artifact-contract.md) for these field meanings, examples and checks; it is used by both ordinary design and reconstruction.

package/payload/desktop-preparation/studio-authoring-template/authoring/studio-creators/source/packages/skills-web-app/bundles/smart_questions/reference/artifact-contract.md

@@ -0,0 +1,245 @@
+# smart_questions output contract
+
+Shared by ordinary design and reconstruction. Canonical state is
+`smart_questions/smart_questions.json`; the installed schema and validation remain
+authoritative. This reference describes representation and semantic checks,
+not permission to invent facts, choose new policy or trigger user review.
+Examples and design recommendations below are not source evidence. In
+reconstruction, preserve observed behavior and supported uncertainty; report
+required facts that cannot be represented rather than fabricating a value.
+
+Restore coherent product background before incidental details, to the extent the source supports it. The shared method below governs organisation; ordinary interview choices and pauses remain in SKILL.md. Preserve actual user answers. Empty, inferred and user-confirmed are different even when all are schema-valid.
+
+## Shared method for design and reconstruction
+
+Read the current user request, existing cards, supplied product understanding,
+GROUND and relevant Design evidence. In reconstruction, also verify focused
+source paths. First connect the evidence into a compact product account:
+who, in which situation, faces which need, seeks which result, through what
+core interaction, within which boundaries. This is reasoning that shapes the
+cards, not a required extra file, summary field or introductory questionnaire.
+
+Use 5W1H as lenses rather than six mandatory cards: who participates; what
+outcome matters; when and where the need arises; why the product is useful;
+and how the user achieves the result. Do not substitute internal architecture
+for the user's "how", or invent a motivation that the evidence cannot support.
+Group related evidence around a meaningful product question; order a new
+overview from purpose and users through the main scenario to scope. Source
+directory order must not become question order.
+
+An initial broad overview should make the product understandable before adding
+incidental details. For an existing well-understood product or a narrow request,
+reuse that overview and address the relevant gap; do not restart an interview.
+Choose the method that serves the current request:
+
+| Method | Purpose | Application |
+| --- | --- | --- |
+| Background study | Establish or revise the product's overall context. | Use the missing, meaningful 5W1H lenses to connect users, needs, outcomes, scenarios and boundaries; an exploratory interview can help the user discover them. |
+| Content completion | Make a clear, bounded deliverable concrete. | Ask only necessary missing content, such as the name to display on a portfolio; do not reopen all product background. |
+| Targeted follow-up | Incorporate a consequential discovery or unresolved decision. | Explain how it changes the established understanding; update its existing card or add a focused question if it is genuinely new. |
+
+A useful card helps understand the product or make a meaningful current decision.
+Before adding one, identify what in the current requested result would change
+with the answer, and why existing evidence or an agreed boundary is insufficient.
+If the only reason is that more features, fields or alternatives are possible,
+omit it. This relevance test applies to question generation itself, not just
+to the recommended option: adding "keep it simple" does not make an unnecessary
+question necessary. Explicit exploration can surface new needs, but a request
+to confirm remaining essentials is not an invitation to expand the product.
+Check whether another facet already owns the topic.
+Do not turn repository findings, every advisory candidate, or a catalog of
+future possibilities into questions. Recheck advisory candidates against current
+evidence and user intent; omit already resolved or currently unnecessary ones.
+Do not manufacture a question or a no-op invocation to consume an action receipt.
+
+### Reconstruction
+
+An explicit reconstruction asks for the same product understanding, obtained
+from implementation and documentation rather than a new interview. Build the
+overview from representative entry points and user journeys, then include only
+material supporting context. Do not ask the user how many Bundles to scan, or
+replace the overview with component, SEO, billing or deployment inventories.
+
+Put a concise source-supported answer in `answer`; use `detail` for exact
+source locations, observation versus supported inference, and remaining limits.
+A supported interpretation may explain the overall product, but label it as
+inferred, not stated user intent. Do not infer commercial positioning or target
+audience merely from the presence of an admin route or a technical capability.
+The visible answer should read as product understanding, not a source-code dump.
+Reconstruction prefill is reviewable, not user confirmation; it is not a license
+to guess answers during ordinary questioning.
+
+If evidence supports part of the answer, retain that part and identify remaining
+unknowns in `detail`. Split independent topics rather than let one known fact
+mask a separate unknown. Leave genuinely unsupported answers empty. Missing
+information in one summary document is not proof of absence in the repository:
+inspect a relevant source when the missing fact matters. Preserve user answers
+and explain conflicting source evidence without replacing their decisions.
+
+Before closing, read the cards as a whole: can a reader understand the product's
+purpose, intended users, main scenario and scope to the extent the source permits?
+Are later details supporting that account rather than displacing it? Check that
+`detail` does not contain a verified answer missing from `answer`, that unknowns
+remain honest, and that each inference is supported. This is an Agent self-check,
+not a new validator or host gate.
+
+## Fixed-card contract
+
+The executor carries these stable definitions and initialized defaults into a
+new complete state, and preserves them on revision. Do not presume automatic
+Core seeding: schema checks shape, and the declared Panel policy protects the
+fixed cards' interactions. Keep both existing cards; never rename, replace or
+modify their prompts/options. They are first-round configuration, not a reason
+to repeat an interview.
+
+| ID | Question | Values | Default |
+| --- | --- | --- | --- |
+| `const_auth_mode` | 是否需要注册登录？ | `anonymous` / `auth_required` | `anonymous` |
+| `const_storage_mode` | 应用数据如何保存？ | `browser_temp` / `database_persistent` | `browser_temp` |
+
+Their recommended choices match the initial defaults. Never attach `round` or
+`rejected` to fixed cards or offer rejection. Preserve actual user answers and
+details. In reconstruction, verify login and persistence instead of treating
+defaults as evidence. If neither choice faithfully describes the implementation,
+leave the answer empty and explain its actual scope in `detail`; durable files
+do not imply cloud sync or a database. In ordinary authorized defaulting, retain
+defaults unless the requirement establishes another choice.
+
+## State contract
+
+`questions` is the complete set of cards rendered in the current FE panel. The
+map key is the stable question ID; do not duplicate it inside the card. Do not
+add hidden queues, answered/rejected ID lists, categories, priorities, 5W1H
+labels, strategies, or any other planning metadata. The optional top-level
+`rounds` map is solely independent display copy for existing question rounds;
+it is not a planning queue, answer store or another lifecycle authority.
+
+The complete payload is an object whose `questions` value is a map from
+question ID to its question object, with optional `rounds` keyed by the saved
+round's decimal string. This synthetic example is not a user requirement or
+confirmation; the fixed answers below demonstrate initialization only:
+
+```json
+{
+  "rounds": {
+    "0": {
+      "title": "AI 使用方式",
+      "description": "合成示例：澄清 AI 如何帮助用户完成当前任务。选项是待讨论的提案，不是已确认需求。"
+    }
+  },
+  "questions": {
+    "const_auth_mode": {
+      "prompt": "是否需要注册登录？",
+      "kind": "single",
+      "choices": [
+        {"value": "anonymous", "label": "不需要，直接使用", "recommended": true},
+        {"value": "auth_required", "label": "需要，支持注册登录", "recommended": false}
+      ],
+      "answer": "anonymous",
+      "detail": ""
+    },
+    "const_storage_mode": {
+      "prompt": "应用数据如何保存？",
+      "kind": "single",
+      "choices": [
+        {"value": "browser_temp", "label": "仅当前浏览器临时保存", "recommended": true},
+        {"value": "database_persistent", "label": "持久保存，可跨设备继续使用", "recommended": false}
+      ],
+      "answer": "browser_temp",
+      "detail": ""
+    },
+    "ai_interaction_method": {
+      "prompt": "用户如何与 AI 交互？",
+      "kind": "single",
+      "choices": [
+        {"value": "button_trigger", "label": "点击按钮触发分析", "recommended": true},
+        {"value": "dashboard_widget", "label": "在报表页展示 AI 洞察卡片", "recommended": false}
+      ],
+      "answer": "",
+      "detail": "",
+      "multimodal_answer": [],
+      "round": 0,
+      "rejected": false
+    }
+  }
+}
+```
+
+The first two entries are fixed in state. The FE renders them at the bottom of
+the first round only; add dynamic questions after them and the FE renders later
+dynamic rounds without those fixed cards, newest first. When editing an
+existing panel, carry the fixed-card definition and prior user decisions
+forward into the complete canonical state without adding them to the new round.
+
+- `value` is the stable selection token. `label` is visible text. Answers always store `value`, never a label, recommendation suffix, or invented internal token.
+- `single` stores one `value`; `multiple` stores comma-separated `value`s; `text` stores its substantive free-text response in `answer` and has no choices. A known answer must not exist only in `detail`; the answer should remain understandable without opening the supplementary explanation.
+- `recommended` is the only recommendation mechanism. Do not add a question-level `suggest` field or append `(推荐)` to stored labels.
+- Dynamic-card `round` controls the FE's round grouping; the latest round renders
+  first. Assign a nonnegative integer explicitly: use 0 for the first dynamic
+  round; when genuinely new topics need a later round, use one greater than the
+  greatest existing dynamic grouping value (normalize legacy values as below
+  for this calculation only). Do not rely on automatic write-time allocation.
+  Missing legacy round values group as 0; the existing view clamps negative
+  values to 0 and truncates fractions for grouping only. Preserve those saved
+  values on unrelated edits rather than silently renumbering history. Fixed
+  cards do not participate in round-number allocation.
+- `detail` records the user's optional explanation, constraints, or source/provenance notes in reconstruction; it supplements rather than duplicates the answer. Preserve older detail-only records without automatically promoting uncertainty or provenance into an answer. When the user answers
+  a choice question with wording that does not match a rendered option, keep
+  `answer` empty and preserve the exact wording in `detail`; never replace it
+  with a recommended option. On dynamic cards, `rejected` means the user
+  rejected this question; it remains a visible design record. A truly deleted
+  dynamic question is removed from the map. Fixed cards cannot be rejected.
+- `multimodal_answer` stores up to five unrestricted local-file references.
+  New references use `type: "file"` (`"image"` remains valid for legacy
+  references), a 32-character hexadecimal `file_md5`, a path-free filename,
+  a normalized `mime_type` (falling back to `application/octet-stream`), and a
+  positive `size_bytes` value no larger than 10 MiB. Design Panel uploads are
+  persisted locally as Bundle-owned Design Files under
+  the relative `artifact_file` under `smart_questions/attachments/` in the same
+  atomic checkpoint as this JSON. New files use a SHA-256 filename while
+  `file_md5` remains the stable compatibility digest. Never store base64, a
+  temporary upload token, an OSS URL, or an absolute host path in canonical
+  state.
+- The UI derives response presence from non-empty `answer` or
+  `multimodal_answer`; supplementary `detail` alone does not answer the question.
+  Do not persist a duplicate `is_answer` flag. Response
+  presence does not establish user confirmation or resolve an unknown.
+
+### Independent round introductions
+
+For each new dynamic round, author `rounds["<round>"].title` and `description`
+as nonempty strings. The key is the actual saved round number's base-10 string
+(e.g. saved `round: 7` uses `rounds["7"]`, even when displayed as “第2轮”),
+not the consecutive display label, question ID or insertion index. The schema
+requires both string fields on a present entry; their usefulness/nonemptiness
+and matching the questions are executor checks, not a title-length validator.
+
+Use a short topic title: Chinese preferably no more than 12 characters, English
+a short phrase. Do not hard-truncate user text. Describe the round's purpose,
+context and current decision in `description`, without inferring user approval
+or inventing product facts. A title must not be the first question's prompt or
+a generated extract from it. Each question still has its own complete `prompt`,
+including the proposal, useful context and concrete decision when needed;
+round-level copy does not excuse an incomplete or ambiguous question.
+
+Only question membership determines round order, current round, answered counts
+and history protection. Metadata alone cannot create a pending round, force an
+interview or count as an answer. Preserve all unrelated introductions, question
+IDs, prompts, answers, details, rejections and attachment references during a
+complete-state revision. Deleting or revising the first question must not derive
+or overwrite the round's introduction. Do not automatically delete unrelated
+metadata while editing a card.
+
+Existing files without `rounds`, or with no entry for an old round, remain
+readable. Show a generic localized round label in that case; do not reconstruct
+copy from the first question or mutate canonical state merely to render it.
+If an authorized revision adds metadata for a legacy fractional/negative round,
+use the existing view's normalized grouping key without changing its cards.
+New rounds use integer values. Both ordinary design and reconstruction follow
+these preservation and evidence boundaries; introductions are display context,
+not user answers or source-supported evidence by themselves.
+
+Choice questions require at least two choices whose `value` and `label` are
+non-empty. Integration validation requires every answered choice to resolve to
+an option currently rendered by the FE. An invalid value is a failed write,
+not a successful answer.