crates

Imported from oku-theory/oku-slides (crates/AGENTS.md). Install upstream with npx skills add oku-theory/oku-slides --skill crates. Copyright stays with the author.

crates — agent rules

Invariants

• Compute a theme's effective tokens only through oku_slides_core::tokens::effective_tokens, never a local copy. (plan:2026-10-10-import-pptx-lot2)
• Create Renderer or Registries directly only in worker serve.rs, the CLI and render tests; else use RenderWorker. (plan:2026-09-29-compilation-bornee)
• Verify packs only via PackFiles::matches or PackVersion::verifies; adopt the default packs only via adopt_default_packs, and add missing pack requirements only via closure_ops. (plan:2026-10-02-creation-widgets, plan:2026-10-18-packs-lot1-widget-packs)
• Refuse widget files over max_widget_kib or beyond max_widgets per version (counting _commun), and never execute them. (plan:2026-10-02-creation-widgets)
• Never mutate sources.deck directly; change the deck only through SourceBundle apply or apply_silent. (plan:2026-09-27-sources-loro-fondation)
• Return MCP tool and agent-form errors localized via Fluent in the user's language, never as raw English text. (t-403, t-650)
• Localize hub, MCP tool and agent texts via LiveLocalizer::current at each use, never a launch snapshot. (t-793)
• Keep dataset ids and columns aligned with source on every core write; rereads only repair merged states. (ADR-0004)
• Never make oku-slides-core depend on oku-slides-import; among workspace crates import may depend only on core, chart and i18n. (plan:2026-10-09-import-pptx-lot1, plan:2026-10-10-import-pptx-lot2)
• Never write a deck-only pack (PackScope::Deck) to the library; its new versions stay deck-only; themes have no scope. (t-692, t-1098)
• Add or remove a Rust advisory exception in deny.toml and .cargo/audit.toml together, with its reason in deny.toml. (t-890, t-897)
• Fix clippy pedantic lints instead of lifting them per crate or workspace; expect one at the site with a reason. (t-1186)
• Keep unsafe_code at deny, not forbid: FFI modules lift it with #[expect(unsafe_code, reason)]. (t-1186)
• Route lossy numeric casts through oku_slides_core::num; crates below core keep a local num.rs with the same names. (t-1186)

Pitfalls

• Bump rust-toolchain.toml with every CI dtolnay/rust-toolchain pin (tag and SHA forms), fixing new lints in that commit. (t-1201)
• Do not add create_dir_all or exists checks around storage; write_atomic, list_files and delete handle absence. (plan:2026-10-08-sessions-par-perspective)

Testing

• Make probe budget tests deterministic: use probe_budget_ms = 0 and assert behaviour, never measured elapsed time. (t-571, t-576)
• Start an integration test crate that panics in helpers with #![expect(clippy::panic, reason)]; allow-panic-in-tests skips them. (t-1186)
• Under heavy machine load, re-run timed-out render-worker, local-agent or CLI import tests with nextest --retries 2 before blaming a change. (t-1154)

Settled decisions

• Serve HTTP through the bounded accept loop in oku-slides-platform listen, never bare axum::serve. (t-637)
• Treat a version 1 sources envelope in a PDF as absent and never convert it. (ADR-0002)
• Resolve a language with oku_slides_i18n::resolve instead of building a full Localizer. (t-490)