plotforge

Imported from zhu1090093659/plotforge (AGENTS.md). Install upstream with npx skills add zhu1090093659/plotforge. Copyright stays with the author.

PlotForge Agent Rules

This file is the project-level memory for future agents. Keep durable engineering constraints here; do not use it as a task log.

Project Goal

Build PlotForge as a CLI-first Rust engine with a creator desktop UI adapter. The engine includes opt-in real text, image, TTS, and moderation provider paths plus MCP tools, while local-pi remains the default no-network text path. Steamworks upload, hosted sharing, and paid Workshop integrations remain deferred until their planned tasks.

The current MVP contains:

• Rust workspace crates for schema, storage, rule evaluation, story craft review, local and real-provider agent planning, MCP, runtime, media asset registry, job queue core, static export, Studio adapters, and CLI.
• apps/player-web/static as the source for the no-network static player package copied by plotforge-export.
• apps/creator-desktop as the Vite/React/Tailwind Studio frontend workspace with dashboard, source editor, playtest, runtime trace views, and a thin Tauri command bridge.
• Folder project source of truth using TOML, JSON, Markdown, and generated local assets.
• Rebuildable SQLite cache/index under .plotforge/cache.sqlite for project summary, source file hashes, trace metadata, and asset metadata.
• Export profiles and ai-usage.json as redaction-safe package disclosure surfaces; they describe capabilities and AI usage evidence but do not provide legal conclusions or platform approval promises.
• plotforge-workshop as a local-only Workshop package schema and validator; it validates draft package metadata, file hashes, and disclosure files without Steam API or upload dependencies.
• Steam Submission Kit draft generation in plotforge-workshop; it emits local checklist, AI disclosure, content warning, and packaging-note Markdown drafts without legal, approval, or upload claims.
• Steam compliance QA boundary in docs/steam-compliance-qa.md, enforced by scripts/qa/no_launch_promise_lint.py for active project-facing guidance surfaces.
• No default/example project is committed or auto-loaded; smoke flows create temporary starter projects with plotforge new project.
• Static web export served from local files over HTTP.
• Spec-driven GitHub issues are task/progress units, but pull requests are Phase-level delivery units; do not open one PR per small task during PRD completion work.

Source of Truth

• plotforge-schema is the only schema contract source of truth.
• Generated frontend contracts live in contracts/; regenerate them with scripts/contracts/export_contracts.sh after Rust schema changes and verify with scripts/contracts/check_contracts.sh.
• Folder project files are the source of truth for game projects; generated caches, exports, traces, and build artifacts must be rebuildable.
• Structured editing documents for World, StoryCraft, Characters, State variables, and Rules are schema-defined contracts backed by plotforge-storage source files; regenerate frontend contracts after changing them.
• SQLite cache/index files are never required to load canonical project state; when cache contents conflict with folder files, folder files win and the cache must be rebuilt.
• Temporary starter projects generated by plotforge new project are the smoke-test source of truth for CLI/export flows.
• Runtime traces are generated evidence, not committed fixture state.
• Runtime traces must use structured, redaction-safe fields for action intent, rule result, planner result, diagnostics, media references, fallback, and errors; do not write raw provider responses, secrets, or unredacted key markers into trace/debug output.
• Runtime traces, snapshots, and provider output envelopes must carry reproducibility metadata (run_seed, prompt_version, model_version, provider_config_hash, optional mcp_tool_call_hash / moderation_config_hash, and trace/snapshot evidence ids where applicable) without storing raw provider responses or credentials.
• The retired docs/design/ui-mockups/agent-native-v1/ PNGs/README were historical development-time visual references only and are no longer present; the original design intent for the Agent Mesh, Command Center, Director Mode, proof, trace, and export package workflows now lives in the running Studio UI (apps/creator-desktop/src). Do not reintroduce those mockups and do not reference them from apps/creator-desktop/src.
• Real provider configuration is local-only: credentials must be injected through explicit local resolvers such as environment variables, provider config hashes must be derived only from non-secret config fields, and providers/ or provider_config.* files must never become project source, contracts, traces, or export package content.
• The user-global Provider registry (~/.plotforge/providers.json or the platform config-dir equivalent), the Skills library (~/.plotforge/skills/, ~/.plotforge/skill-index.json), and the MCP server registry (~/.plotforge/mcp.json) are user-global local-only configuration; they never enter project source, contracts, traces, or export packages. Credentials are referenced indirectly by environment-variable name (credential_env_var); the registries never store credential values. Every Provider registry mutation must use the agent-owned locked transaction boundary covering the complete load-modify-write cycle and an atomic same-directory replacement; Studio/Tauri/CLI adapters must not implement separate registry locks or direct read-modify-write sequences.
• Prompt templates are split into a user-global library (~/.plotforge/prompts.json, shared across projects) and an optional per-project store (<project>/.plotforge/prompts.json). Project-scoped templates stay under .plotforge/ and are blocked from export packages by the export allowlist and the workshop denylist; user-global templates never enter any project.
• Built-in prompt templates are code-managed, versioned compile-time constants (PromptTemplate { id, version, system_message, output_instructions } in plotforge-agent::prompts), not user-edited files; their version string (e.g. scene_planner_v1, beat_writer_v1, plot_doctor_v1) flows into ReproducibilityMetadata.prompt_version on every agent output envelope so a change to a template's system/output text is a version bump that reproducibly distinguishes runs. Editing a built-in template's wording is a version increment, never a silent edit.
• Real provider calls (text, image, TTS, and moderation) are in scope for plotforge-agent and shipped behind the production HTTP clients (OpenAiCompatibleClient / OpenAiResponsesClient / AnthropicMessagesClient for text, OpenAiImageClient for images, OpenAiTtsClient for TTS, and OpenAiModerationClient for moderation). The offline local-pi path remains the default no-network scene-planning path and derives its proposal from creator input and project context; generic fake providers are test-only. A fully no-network apply also leaves real media providers disabled. Real provider calls occur only through explicit enabled configuration. Provider configuration and recorded evidence stay local-only and redaction-safe: no raw provider response body, credential, or unredacted key marker enters traces, the persisted registry, project source, contracts, or export packages.
• Dynamic model discovery (fetch_provider_models) queries a provider's upstream /models (or Anthropic /v1/models) endpoint and caches the list locally under ~/.plotforge/cache/models/{provider_id}.json with a 1-hour TTL (MODEL_DISCOVERY_TTL_SECS = 3600); a fresh cache is returned as-is and a stale/missing cache triggers a fresh fetch. The cache stores only redaction-safe RemoteModelInfo metadata (id, owned_by, created, max_input_tokens, max_output_tokens) — never credentials, endpoint response bodies, or secrets. The credential is resolved through the same strict EnvCredentialResolver as completions; a missing credential surfaces ModelDiscoveryError::MissingCredential, never a silent empty list.
• External Skill auto-discovery scans a fixed set of roots: ~/.plotforge/skills, ~/.claude/skills, ~/.codex/skills, ~/.zcode/skills, ~/.cursor/skills, ~/.copilot/skills, ~/.hanako/skills, ~/.openclaw/skills, ~/.workbuddy/skills, ~/.redbox/skills, and ~/.codex/vendor_imports/skills/skills/.curated. Roots that do not exist on this machine are silently skipped (not errors, not silent fallbacks). PlotForge never creates directories under any external root; it only reads and copies into its own ~/.plotforge/skills/ library.
• Media asset records must use structured, redaction-safe provider metadata only; store prompt hashes/request ids when needed, never raw provider responses or secrets.
• Job records must use typed state, explicit failure objects, injected clocks for deterministic tests, and no hidden global async state.
• The user-global UsageLedger lives at ~/.plotforge/usage.json (or the platform config-dir equivalent) and is owned by plotforge-job. It stores only redaction-safe per-call provider/model identifiers, generation kind, token counts, cost units, and timestamps; it never stores prompt content, response bodies, credentials, or secret markers, and it never enters project source, contracts, traces, or export packages. Missing ledger files mean no recorded usage; corrupt files fail explicitly rather than silently resetting accounting. Path-backed appends must reload under the ledger's cross-process lock and atomically replace the file in the same directory, so concurrent or stale handles cannot overwrite another call's usage; adapters use report_usage rather than owning a second persistence path. Non-local apply flows validate the ledger before any moderation/text/MCP request, then share that ledger through moderation, text/MCP, and image accounting; local-pi keeps the no-ledger fast path. Every successful moderation response is recorded exactly once as UsageKind::Moderation before the flagged/pass branch, using stable provider ids and zero token counts when the upstream omits usage, so blocked calls and cost units remain visible.
• Image provider fallbacks must remain trace-visible and must register placeholder assets as fallback metadata, not as successful generated-cache hits.
• Spec-driven planning artifacts and progress logs are local/private operator state for this open-source repository; keep them out of Git and under ignored paths unless explicitly approved.
• For broad PRD completion phases, prefer parallel sub-agents for disjoint implementation lanes after shared schema/contracts are planned; keep final integration, validation, and Phase PR scope decisions centralized.

Architecture Boundaries

• Keep rule evaluation in plotforge-rule; do not duplicate rule behavior in CLI, UI, storage, export, or tests.
• Keep runtime state transitions in plotforge-runtime; agents propose content and runtime/rules commit state.
• Runtime owns Scene/Beat progression: same-scene choices such as continue advance through BeatNext::Beat without planner calls, scene changes, new images, or turn increments; change_scene choices cross the planner/runtime boundary, set the next scene entry beat, and increment the turn. Production RuntimeSession::new uses NoScenePlanner, so crossing a scene boundary without pi-Agent or an explicitly injected provider fails with scene_planner_required; MockAgentPipeline is test-only.
• Missing current beats, entry beats, or same-scene beat transitions must fail explicitly; do not silently fall back to another beat when committing runtime state.
• Player/freeform input must resolve to a typed ActionIntent; unsupported input must not mutate runtime state or silently map to a default action.
• Keep persistence and fixture file layout in plotforge-storage.
• Keep structured editing read/update/create behavior in plotforge-storage and expose it through plotforge-studio/Tauri command adapters; Creator Desktop must call the generated-contract bridge instead of parsing or validating project files in TypeScript.
• Keep SQLite cache/index behavior in plotforge-storage; it may index project summaries, source file hashes, trace metadata, and asset metadata, but must not become a second project loader or source of truth.
• Keep static export behavior in plotforge-export; exported bundles must copy only reachable referenced assets from plotforge-media and must not include private traces, provider config, raw provider responses, unreferenced assets, or secrets.
• Export profiles and AI usage manifests must stay schema-defined, redaction-safe, and capability/descriptive only; do not put provider credentials, raw provider responses, private traces, legal conclusions, or platform approval promises into them.
• Keep Workshop package validation in plotforge-workshop; it must remain local/offline validation of draft package metadata and file hashes, not a Steamworks SDK wrapper, upload client, or release-readiness oracle.
• Keep Steam Submission Kit generation in plotforge-workshop; it may generate local draft documents from validated package evidence, but must not claim compliance, approval, publishing automation, or legal conclusions.
• Keep Steam-facing docs and generated guidance under the no-launch-promise QA boundary; do not promise automatic publishing, platform outcomes, legal conclusions, or ownership of a creator's Steamworks workflow.
• Keep static player package behavior in apps/player-web/static; it must consume ExportManifest, run without external network URLs, and must not duplicate rule/runtime state machines. The player is split into player-core.js plus player-save.js/player-i18n.js/player-audio.js/player-types.js modules; every module file must be listed in both plotforge-export's PLAYER_PACKAGE_FILES and scripts/qa/static_export_http_smoke.py's expected whitelist (defence-in-depth), and the smoke test must assert no network URLs across all player JS.
• Keep asset registry records, content hashes, references, provider metadata, and reachability in plotforge-media; as export, runtime, Studio, and future providers integrate media, consume this boundary instead of adding a second media registry implementation.
• Keep long-running task state transitions, cancel/retry/timeout/progress, and cost accounting in plotforge-job; provider/runtime/export adapters should not own parallel job state machines.
• Keep the shared pre-flight ThrottleGate in plotforge-job, configured through its provider-agnostic ThrottleConfig. plotforge-agent owns one explicit process-level throttle registry keyed by provider kind, the stable registry id, and a redaction-safe hash of non-quota upstream identity (API shape/endpoint/model/credential env-var name), so provider adapters rebuilt between Studio turns reuse the same RPM/concurrency state without coupling unrelated registry contexts or entries that reuse an id; moderation normalizes its final request endpoint before hashing so equivalent URL spellings share rate debt. Quota edits reconfigure a gate in place and preserve in-flight permits and consumed rate capacity. Editable provider labels are display-only and must never identify throttle or usage-ledger records. With no quota fields, adapters keep the legacy fast path and do not load the ledger. Provider adapters acquire the gate before entering retry handling; the gate never retries, and the shared text RetryPolicy remains the single retry owner for both one-shot and MCP provider rounds. Rate limits surface an exact retry_after_ms, and concurrency permits release through RAII on every drop path. daily_token_budget is text-only and is enforced from the UsageLedger's current UTC epoch-day output tokens; image, TTS, and moderation entries reject it because those upstream responses do not provide trustworthy output-token accounting. BudgetExceeded is explicitly non-retryable.
• Keep image provider ports and scene image pipeline orchestration in plotforge-agent; image providers should feed plotforge-media and plotforge-job instead of bypassing those boundaries.
• Keep CLI behavior in plotforge-cli; CLI should orchestrate crates instead of owning business logic. CLI output formatting (i18n chrome terms, labels, colorized summaries, report rendering) lives in plotforge-cli/src/cli_output.rs; main.rs only dispatches commands and orchestrates handlers. Color is emitted only when stdout is a TTY (std::io::IsTerminal), so pipes, redirects, and test harnesses see plain text. JSON output (studio commands, serde_json) is never colored and its field shape is a contract — never adjust JSON fields for human-readable changes.
• CLI interactive wizards (e.g. workshop submission-kit) use dialoguer to prompt step-by-step and are the default; --batch explicitly enables full flag-driven input for scripts/tests. Wizards must guard stdin TTY (std::io::IsTerminal) and bail with an explicit error directing to --batch when non-TTY — never hang on a blocked stdin or silently fall back. Wizards only collect parameters; business validation and generation stay in the owning crate (plotforge-workshop), never reimplemented in the CLI.
• Keep apps/creator-desktop as an adapter over generated contracts and future Tauri commands. TypeScript UI code may import types from contracts/plotforge.d.ts, but must not reimplement rule, runtime, storage, storycraft, or agent business logic.
• Creator Desktop UI is split into one View component per workspace region (App.tsx renders LaunchpadView[=Home], PlayView, WorldView, StoryView, CharactersView, StateView, RulesView, AssetMaintenanceView[=Assets], TraceDebugView[=Trace], ExportView, SourceView, SettingsView[=Settings]). Navigation is a single flat list (studioModel.ts: studioSections), not a two-level workflow/section tree. App.tsx only orchestrates routing, layout, and form-action sinking into useStudioWorkspace sub-hooks (useProjectEditing/usePlaytest/useExport/useAgentConversation). New regions go in their own *View.tsx, never as inline render*Panel functions in App.tsx. SourceView owns the project source-file browser and inline text editor; LaunchpadView (Home) is a project-entry + health surface only (no source editing, no run button, no director-input box) and renders inside StudioShell so the sidebar, agent rail, command palette, and collapse toggles are reachable from Home — Home is no longer a full-screen branch outside the shell. The right-side AgentChatRail is the single "describe a change / run a turn" entry point — the shared playtestInput state lives in usePlaytest and is consumed by useAgentConversation; no other view may render a director-intent textarea or "run proof" button. PlayView is the single read-only scene preview (background image + current beat + choices); clicking a choice submits choice.label as the next turn's intent via agent.submit(). Snapshot controls (saveId/restoreId/restoreLatest) live in a "Advanced snapshot controls" Collapsible inside TraceDebugView, not in a separate Director Mode view. The honesty-surface boundary evidence lives on demand inside the AgentChatRail "Evidence" popover (a Collapsible "Local boundaries" block), not as an always-painted panel or a top-level AgentMeshView. Structured-document creation (e.g. createCharacterFromDraft, createRuleFromDraft) must sink to plotforge-studio Rust commands via the contract bridge, never be reimplemented in TypeScript. runtimeTraceView.tsx is an orphan skeleton superseded by TraceDebugView; do not revive it. The retired CommandCenterView, DirectorModeView, AgentMeshView, and ArtifactReviewView were deleted when the navigation was flattened; do not reintroduce them or their two-level workflow grouping.
• SettingsView (sidebar item #12) is the single entry point for Agent / MCP / Skill configuration: it owns three internal Tabs (Agent / MCP / Skills). The Agent tab (AgentConfigSection) covers text, image, TTS, and moderation provider subsections plus Model, Prompts, and the read-only usage summary; moderation remains a subsection here, never a fourth top-level Settings tab. The MCP tab (McpSection) renders the real MCP server management surface (list, add/edit/delete, stdio/sse/http transport config, Test connection → McpServerTestResult, per-project enable toggle persisted to AgentSessionConfig.enabled_mcp_servers, tool list with Invoke → redacted McpToolCallResult) — it is no longer a "coming in a future release" placeholder. The AGENTS.md boundary carve-out for MCP server calls has landed (see the MCP carve-out paragraph below); the schema types, plotforge-mcp crate, Studio commands, contracts, and DataSource methods are implemented. The Skills tab (SkillsSection) covers the user skill library and per-project enablement. Provider entries carry only credential_env_var (the env-var name), never the credential value; the UI must never display or collect secret values. Model settings (model_id / permission / thinking / enabled_skills / enabled_mcp_servers) are persisted through useAgentConfig → set_agent_session_config. The shared agentConfigSelectors.tsx (ModelSelect / PermissionSelect / ThinkingSelect) is the single source of truth for the model/permission/thinking selectors so the Home toolbar (LaunchpadView) and the Settings → Agent tab render the same AgentSessionConfig with the same UI. Prompt templates are split user-global / project-scoped. Skills are auto-discovered from external roots and imported into the user library; enabling a skill for a project writes its id to AgentSessionConfig.enabled_skills.
• Keep HTTP provider client behavior in plotforge-agent; the three supported API formats (openai_compatible / openai_responses / anthropic_messages) all implement the TextModelClient trait, are constructed by build_provider_client/build_text_provider from a ProviderEntry, and resolve credentials through EnvCredentialResolver / OptionalEnvCredentialResolver. Credentials are never stored in struct fields, traces, or the persisted registry. Skills auto-discovery scans the fixed external roots (see Source of Truth) and stores only metadata in SkillManifest; skill bodies are loaded on demand via load_skill_body (progressive disclosure).
• Provider HTTP error handling is coordinated, not ad-hoc: a non-2xx 429 Too Many Requests surfaces the RateLimit { retry_after_ms } kind (parsed from the Retry-After header, seconds or HTTP-date), other non-2xx surface as Provider, and timeouts surface as Timeout. The text retry policy (RetryPolicy::default()) caps at max_attempts = 3 with exponential backoff (base_delay_ms = 500, max_delay_ms = 8_000, jittered) and honours the server-advised retry_after_ms (clamped to max_delay_ms) when present. Retryable kinds are RateLimit, Provider (5xx), and Timeout; ContentFiltered and OutputTruncated are non-retryable (retrying with the same prompt/limit reproduces the same outcome and burns quota), so the retry loop surfaces them immediately with an attempt-count annotation in the message. Image and TTS providers mirror this: 429 → RateLimit, content-filter → non-retryable ContentFiltered, with their own IMAGE_JOB_MAX_ATTEMPTS = 2 / TTS_JOB_MAX_ATTEMPTS = 2 job-level caps.
• Image and TTS providers are registered in their own ProviderRegistry arrays (image_providers: Vec<ImageProviderEntry>, tts_providers: Vec<TtsProviderEntry>), separate from the text providers list, and resolved by resolve_image_provider / resolve_tts_provider (first enabled entry, or None — the pi-Agent / TTS pipelines skip generation when None rather than failing the turn). Both entry types follow the same credential_env_var-name pattern as ProviderEntry: the registry stores the env-var name only, never the value, and the value is resolved at call time (OpenAiImageClient via the injected ProviderCredentialResolver; OpenAiTtsClient via EnvCredentialResolver internally). A missing/empty credential for an auth-required provider surfaces an explicit image_provider_missing_credential / tts_provider_missing_credential error — no silent degraded run. image_providers and tts_providers are #[serde(default)] so a registry serialized before they existed still deserializes.
• TextModelRequest carries an additive messages: Option<Vec<ChatMessage>> field (T2.1/T2.2). When Some, the three HTTP clients send the structured {role, content} conversation verbatim per their wire format (OpenAI Chat Completions → messages array; OpenAI Responses → instructions + input split; Anthropic Messages → top-level system + messages array); when None, the single prompt is wrapped as one user message (the pre-T2.2 shape). This field is strictly additive: the TextModelClient trait signature and the three complete() methods are NOT modified, and None preserves the prior behaviour. A secret-marker scan runs over each message's content at the same redaction boundary as prompt before it leaves the process.
• TextProviderConfig carries a supports_json_schema: bool flag (T2.4). When true, the HTTP clients use provider-native JSON Schema mode to constrain output to a valid AgentOutputEnvelope shape: OpenAI-compatible/Responses send response_format: {"type":"json_schema","json_schema":{"name":"agent_output_envelope","schema":<AgentOutputEnvelope schema>,"strict":true}}; Anthropic Messages defines a forced emit_envelope tool with the envelope as its input_schema and parses the tool_use block's input. When false, OpenAI-compatible keeps the json_object response format and Anthropic sends plain messages with no tool constraint (the pre-T2.4 shapes). The flag is deliberately excluded from provider_config_hash — it is a client-side capability flag, not part of provider identity. The schema is generated once via schemars::schema_for!(AgentOutputEnvelope) and matches the same JsonSchema impl that backs contracts/plotforge.schema.json.
• AgentChatRail's "describe a change / run a turn" drives the pi_agent_apply_run Studio command: the pi-Agent generates a ScenePlan proposal via the configured provider (offline input-derived provider when model_id == "local-pi", or a real HTTP provider), RuntimeSession::apply_agent_scene_plan evaluates rules (change_scene action type) and commits the proposal through commit_scene_plan, and the result is appended as a chat turn carrying a PlayOnceReport-shaped PiAgentApplyResult. usePlaytest remains the owner of snapshot-control state (playtestSaveId/restoreId/restoreLatest) and the shared playtestInput; the rail mirrors the latest report into playtest.setPlaytestReport so TraceDebugView/PlayView stay in sync, but the rail's main submit path no longer drives play_once_project*. Failure modes are explicit (pi_agent_missing_credential, pi_agent_provider_timeout, pi_agent_unsupported_payload); no silent fallback.
• Agent-native Creator Desktop UI may show pi-Agent runtime, agent capabilities, approvals, and evidence as explicit local workflow surfaces. Real internal pi-Agent execution (local, schema-backed, redaction-safe, wired through plotforge-agent/plotforge-studio via the pi_agent_run/pi_agent_capabilities Studio commands) is permitted and must stay local-only. External agent execution, hidden network model calls, Steam upload automation, legal conclusions, or platform approval remain forbidden unless those schema-backed integrations are explicitly added.
• Keep i18n as an adapter concern for UI chrome and command output, with full English/Chinese coverage for every user-visible chrome string. Creator Desktop text is localized through apps/creator-desktop/src/i18n.tsx; static player text is localized through apps/player-web/static/player-i18n.js (split from player-core in T5.1); CLI output uses the OutputLanguage selector (--language / PLOTFORGE_LANGUAGE). Do not automatically translate project-authored titles, source files, story text, manifest content, or creator-provided export metadata.
• Keep Tauri command behavior in testable Rust adapter crates such as plotforge-studio; apps/creator-desktop/src-tauri should stay a thin IPC wrapper.
• Do not add Steam/Workshop upload integrations, provider SDKs, or unplanned networked model calls to MVP core crates unless the project scope is explicitly changed. The real HTTP provider family in plotforge-agent—text, image, TTS, and moderation—is explicitly in scope and is not a violation of this rule. These are first-party reqwest clients built from schema-defined registry entries, never third-party provider SDKs; their configuration and recorded evidence stay local-only + redaction-safe per the Source of Truth and moderation carve-out rules. The rule still forbids pulling a vendor SDK (OpenAI/Anthropic/etc. official client libraries) into any crate.
• MCP (Model Context Protocol) server calls are an explicit, scoped exception to the "no networked model calls" rule above. This carve-out permits MCP client behavior (stdio subprocess + SSE/HTTP transport, server lifecycle, tool discovery/invoke) in a new plotforge-mcp crate that depends only on plotforge-schema + transport dependencies; plotforge-agent depends on plotforge-mcp, never the reverse (preserves the schema ← mcp ← agent ← studio DAG). MCP server calls are local-only configuration: the user-global ~/.plotforge/mcp.json (third member of the providers/skills/prompts family) never enters project source, contracts, traces, or export packages; credentials are referenced indirectly by credential_env_var name only, never stored as values. MCP tool-call arguments and results are a new provider-response surface — they must pass through contains_secret_marker_text / redact_trace_text and enter traces only as redaction-safe summaries (tool name, server id, content-block kind, content hash), never raw bodies; an mcp_tool_call_hash (derived from non-secret config fields, mirroring provider_config_hash) is carried in reproducibility metadata. The tokio async runtime is scoped to plotforge-mcp only (for SSE streaming); plotforge-agent and all other workspace crates must not pull tokio as a direct dependency — plotforge-mcp exposes a blocking façade (McpToolRegistry) to the agent. MCP tool-use integration uses a new McpToolClient port trait + a complete_with_mcp_tools wrapper orchestrator; the existing TextModelClient trait and its three production impls are NOT extended or modified (the wrapper runs the multi-turn tool-call loop outside complete_text_agent_output). Transport failures are explicit (mcp_spawn_failed, mcp_handshake_failed, mcp_tool_error, mcp_transport_unsupported, mcp_unknown_server, mcp_io); no silent fallback to a no-MCP path. Per-project MCP enablement persists via an enabled_mcp_servers: Vec<String> field on AgentSessionConfig (with #[serde(default)] for backward compatibility), mirroring the enabled_skills pattern. The CLI exposes MCP server management via a thin mcp subcommand (orchestration only, never reimplements transport logic). MCP UI copy must not promise tool outcomes, automatic publishing, platform approval, or legal conclusions (no_launch_promise_lint.py enforced).
• Moderation provider calls are an explicit, scoped member of the real-provider family. plotforge-agent::providers_moderation owns the independent ModerationProvider port, OpenAiModerationClient, and blocking hand-written reqwest adapter; vendor SDKs and a direct tokio dependency remain forbidden, and tokio stays scoped to plotforge-mcp. moderation_loop.rs performs at most one optional pre-flight over the exact player input before Studio enters either its one-shot text or MCP-assisted text path; it does not widen TextModelClient, call text/MCP providers itself, or own a retry loop. local-pi remains the only no-network text path and never loads or invokes moderation configuration. Moderation entries live only in the user-global ProviderRegistry.moderation_providers at ~/.plotforge/providers.json; ModerationProviderEntry.credential_env_var stores an environment-variable name, never a credential value, and persisted entries are revalidated at the runtime build boundary before any network call. Successful response bodies are capped at one MiB, scanned with contains_secret_marker_text before parsing, and normalized category labels are scanned again before exposure; traces/contracts receive only the schema-owned summary plus a redaction-safe moderation_config_hash, never a raw response, prompt, credential, or secret marker. JobKind::ModerationGeneration, UsageKind::Moderation, and ReproducibilityMetadata.moderation_config_hash are additive contracts, but the pre-flight loop must not grow a parallel job state machine. RPM/concurrency use the shared provider throttle registry keyed by a canonical request endpoint identity so equivalent URL spellings cannot reset rate debt; moderation daily_token_budget is rejected while upstream responses lack trustworthy output-token accounting. When no moderation provider is configured, pre-flight is an explicit pass-through with no moderation hash; a configured provider failure or flagged result is explicit and never silently falls back to an unscreened text call.

Testing Policy

• Every new feature must include corresponding tests in the same change.
• Every bug fix should include a regression test that fails before the fix when feasible.
• Schema or serialization changes must include roundtrip/contract tests in plotforge-schema and affected integration tests.
• Rule, runtime, storage, export, media, job, storycraft, and agent behavior changes must include crate-level tests for the changed boundary.
• CLI command changes must update black-box tests under crates/plotforge-cli/tests/.
• Export/player behavior changes must update export tests and, when rendering or interaction matters, the HTTP smoke path.
• Creator desktop changes must run npm run creator-desktop:qa; user-visible UI adapters should add or update TypeScript/Vitest coverage for contract-backed behavior.
• Creator desktop Vitest coverage is behavior-based: assert via role, accessible name, and visible text (getByRole/getByLabelText/getByText), not DOM class names or internal state, so tests survive className/layout refactors and reflect what users actually perceive.
• Static player changes must run npm run player-web:qa and cover DOM interaction, mobile viewport behavior, and no-network package constraints.
• Generated starter projects, traces, caches, and exports must stay out of commits unless they are intentional fixtures.
• CLI/export smoke tests must use temp dirs; do not mutate checked-in fixtures in CI.
• If a meaningful test cannot be added, document the reason in the PR or final response and run the next best validation.

Test Layer Boundaries

Tests live in four layers with non-overlapping responsibilities. Add a new assertion to the lowest layer that can express it; do not duplicate a business assertion across layers.

• Rust unit tests (#[cfg(test)] modules in src/, e.g. src/tests.rs): assert pure crate-internal logic only. No process spawns, no real filesystem writes outside tempfile. This is the only layer that asserts the behavior of a rule, runtime transition, storage edit, or schema rule (e.g. "continue does not advance turn", "secret marker rejected").
• Rust integration tests (crates/*/tests/*.rs): assert cross-crate collaboration through pub APIs. Use create_project_from_request and other public storage/runtime APIs to build fixtures. Assert composition (e.g. "storage + export produces an audited package tree"), not business results already covered by unit tests. Provider HTTP integration tests live in crates/plotforge-agent/tests/provider_integration.rs and are gated with #[ignore] so cargo test and CI skip them; run explicitly with cargo test -p plotforge-agent --test provider_integration -- --ignored. They exercise the full provider pipeline (text / image / TTS / moderation) against in-process std::net::TcpListener mock servers (the capturing_server pattern), verifying request body wire shape, response parse, and error handling through the public client/adapter types — no real provider is contacted. A PLOTFORGE_LIVE_TEST=1-gated stub is reserved for an opt-in real-API smoke and is always skipped in CI.
• CLI smoke (crates/plotforge-cli/tests/cli_smoke.rs): black-box tests of the compiled binary via CARGO_BIN_EXE_plotforge-cli. Each test covers one command group and asserts "call succeeded + output shape" (exit code, presence of expected substrings, generated file existence). Do not re-assert business results that Rust unit tests cover. One mega-test that serially chains every CLI command is forbidden — split by command group so a failure in one group does not block the rest.
• Frontend Vitest (apps/creator-desktop/src/*.test.tsx, apps/player-web/test/*.test.js): assert rendering and user-perceived interaction (DOM, accessibility roles, visible text, click → state change). StudioDataSource mocks must return contract-typed values (PlayOnceReport, RuntimeSnapshot, etc.) so npm run typecheck catches structural drift; never re-implement Rust business logic (trim/split rules, state-machine transitions, rule evaluation) inside a mock. To control mock behavior drift, rely on review discipline plus the Computer Use smoke — there is no low-cost automated guard.

Cross-layer dedup rule: the same business behavior (e.g. "continue keeps turn=0", "export excludes traces") is asserted in exactly one layer — the lowest layer that can express it. Upper layers may assert only that the call passed and that the returned value has the right shape, not that the business result is correct.

Required Validation

Use the narrowest relevant checks during development, then run the full gate before merging broad changes.

• cargo fmt --all -- --check
• cargo check --workspace
• cargo test --workspace
• cargo clippy --workspace --all-targets -- -D warnings
• npm run creator-desktop:qa
• npm run player-web:qa
• python3 scripts/qa/creator_desktop_build_smoke.py
• scripts/qa/full_local.sh
• scripts/contracts/check_contracts.sh

Tempdir CLI smoke commands:

• tmp="$(mktemp -d)"
• cargo run -p plotforge-cli -- new project --path "$tmp/starter-project" --force --concept "A local starter project." --visual-style "clear readable test style" --initial-scene "A creator opens a fresh PlotForge project."
• cargo run -p plotforge-cli -- check "$tmp/starter-project"
• cargo run -p plotforge-cli -- play "$tmp/starter-project" --once
• cargo run -p plotforge-cli -- trace inspect "$tmp/starter-project/traces/latest.json"
• cargo run -p plotforge-cli -- export static "$tmp/starter-project" --out "$tmp/export"
• python3 scripts/qa/static_export_http_smoke.py --export-dir "$tmp/export"

Fixture validation commands:

• No committed default project fixture is expected.

CI and QA

• GitHub Actions (.github/workflows/ci.yml, triggers on main and mvp/** branches) keeps separate jobs for rust-static (fmt + no-launch-promise lint + check + contracts + clippy), rust-unit (needs rust-static), cli-smoke (needs rust-static), and export-smoke (needs rust-static).
• The creator-desktop job runs both npm run creator-desktop:qa and npm run player-web:qa; there is no standalone player-web CI job.
• scripts/qa/full_local.sh is the repeatable local quality gate.
• Creator Desktop build smoke lives at scripts/qa/creator_desktop_build_smoke.py and must stay wired into npm run creator-desktop:qa.
• Creator Desktop Browser/Computer Use smoke lives at scripts/qa/computer_use_creator_desktop.md; verify the Studio shell, source editor, playtest run, runtime trace id, narrative review, diagnostics, and mobile viewport reachability.
• Codex Desktop Computer Use smoke is local desktop QA only and must not become a GitHub Actions dependency.
• For Computer Use export smoke, serve static exports over localhost HTTP, then verify visible title, scene text, choice buttons, and post-click text changes.
• Starting a server is not enough evidence; perform at least one real browser/app interaction when Computer Use validation is requested.

Error Handling and Security

• Do not add silent fallbacks. Any fallback must be visible in trace/debug output and covered by tests.
• Prefer explicit errors over broad catch-all handling.
• Do not hardcode secrets, API keys, tokens, provider credentials, or personal paths into source, fixtures, tests, exports, or docs.
• Static exports must reject obvious secret markers and must not copy private traces or provider configuration.
• Static export package output must be audited against an explicit whitelist of player files, manifest files, and referenced assets; stale or unexpected files in the output package are errors.
• Do not introduce hidden network calls in tests or MVP runtime paths.
• Reference-library imports must store source metadata, authorization/rights metadata, short summaries, and structure notes only; do not store large raw copyrighted bodies in fixtures or project files.

Change Discipline

• Prefer targeted diffs that preserve crate boundaries.
• Remove obsolete logic when replacing behavior; do not layer duplicate sources of truth.
• Keep generated artifacts out of commits unless they are intentional fixtures.
• Update README and relevant docs when commands, workflow, or user-visible behavior changes.
• Keep AGENTS.md updated when a rule becomes durable project memory.