feat: add AI-assisted ISAC authoring

docs/architecture.md

@@ -427,6 +427,101 @@ state changes, phases, and formulas. No route accepts the generated text as
 input, and no server process executes it. Operators edit structured fields; the
 formatter regenerates the listing after each change.
 
+## AI-assisted mechanic drafting
+
+Manual mechanic authoring remains the complete authoring path. The AI assistant
+produces an optional draft for the existing structured editor. It cannot save,
+publish, approve, or submit game data, and it cannot alter application code.
+An author may ignore, revise, or replace any generated field through the manual
+controls.
+
+The shared mechanic editor exposes the mechanic assistant for standard and
+exotic Talents, OS Protocol Talents, Skill Chip Talents, and Specialization
+tree-rank effects. Calculation revisions use a separate assistant contract
+because their typed stage schema and publication authority differ from
+source-owned mechanic programs.
+
+The server owns a versioned mechanic-authoring prompt and context builder. Each
+request receives the source type, progression contract, submitted game text,
+current draft when supplied, code-defined mechanic registries, and the active
+ISAC Attribute catalog. Attribute context includes stable IDs, names, units,
+descriptions, and calculation metadata. The client cannot replace the system
+instructions, choose arbitrary models, attach files, add tools, or add external
+URLs.
+
+The OpenAI integration uses the Responses API with Structured Outputs, no
+tools, and `store: false`. The application stores the bounded clarification
+history needed for the current drafting session. Requests use a fixed
+server-configured model, a privacy-preserving user safety identifier, input and
+output limits, timeouts, duplicate-request protection, and per-agent rate
+limits. The API key remains on the server.
+
+The model returns one structured result:
+
+- `clarification_required` contains bounded questions whose answers affect the
+  calculation model.
+- `draft_ready` contains the typed mechanic draft, assumptions, warnings,
+  readiness state, and a short explanation.
+- `capability_gap` names unsupported runtime behavior, the nearest supported
+  representation, an optional workaround, and the schema, runtime, editor,
+  reference, and test changes a developer would need to add support.
+
+The server validates `draft_ready` output against the response schema and the
+same deterministic mechanic parser used by manual authoring. Unknown events,
+Attributes, value models, scopes, operators, reducers, or outcomes fail
+validation. The client receives no draft when local validation fails.
+
+The author reviews a validated draft and chooses whether to apply it to the
+unsaved editor. Applying a draft changes client form state only. The existing
+module action performs canonical validation, contribution interception,
+approval, persistence, and game-data audit logging after the author initiates
+the normal save flow.
+
+The `ai.mechanic.generate` permission authorizes generation and clarification
+requests. The server checks it for every request. Agents without the permission
+may see the disabled assistant entry point, but they retain all manual controls
+allowed by their data role.
+
+Successful generation operations append sanitized events under the
+`ai_assistance` audit category. Events identify the operator, source type,
+prompt-context version, model, result type, token usage, request ID, and
+validation result. Audit snapshots exclude the API key,
+environment configuration, hidden model reasoning, authentication data, and
+unbounded prompt content. Applying a draft changes client state and creates no
+server event. The owning module's game-data audit event remains the record of
+any saved mechanic change.
+
+### AI-assisted calculation-revision drafting
+
+The calculation assistant converts an operator's plain-language combat-model
+request into an optional draft revision. It receives the current active or
+edited revision, the calculation-stage vocabulary, weapon and Skill profile
+contracts, and the active ISAC Attribute catalog. Its versioned prompt,
+structured response schema, validation, and application adapter remain
+separate from mechanic drafting.
+
+The assistant returns clarification questions, a validated revision draft, or
+a calculation capability gap. A capability gap identifies the missing stage,
+operator, curve, binding, runtime behavior, or validation rule and lists the
+application and test changes needed to support it. The server rejects unknown
+stage keys, locked-position changes, duplicate bindings, invalid Attribute
+references, unsupported operators, and malformed curve or cap values through
+the deterministic calculation-revision parser.
+
+The `ai.calculation.generate` permission authorizes calculation drafting and
+clarification requests. It does not grant revision mutation or publication.
+Applying a result changes the open revision form in the client. The operator
+must review and save that draft through the existing revision action. The
+separate `calculation.publish` permission and activation confirmation remain
+mandatory before the saved draft affects loadout results.
+
+Successful calculation-generation requests append sanitized events under
+`ai_assistance`. These events use calculation-specific actions, identify the
+base revision and generated contract version, and follow the same request,
+token-usage, result, and secret-exclusion rules as mechanic-assistance events.
+Applying a draft creates no server event. Existing `calculation_configuration`
+events remain the evidence for revision saves and activation.
+
 Source authors define the builder controls required by their mechanic as typed
 toggle, slider, or numeric scenario inputs. Each input records its label,
 guidance, bounds when applicable, default value, and best-case value. These