De-Koi

Imported from The-Koi-Pond/De-Koi (AGENTS.md). Install upstream with npx skills add The-Koi-Pond/De-Koi. Copyright stays with the author.

Hard Rules

• Product behavior belongs in src/engine; React UI belongs in src/features; runtime wrappers belong in src/shared/api; privileged/hostable capabilities belong in src-tauri.
• Engine code must not import React, Zustand stores, @tauri-apps/api, feature internals, or concrete src/shared/api adapters.
• New or touched feature code should use focused shared API wrappers, not raw invokeTauri imports or raw remote-runtime fetch.
• Remote-capable behavior must follow the explicit HTTP pipeline documented in de-koi-architecture-guard.
• Coding agents must load and apply skills/de-koi-architecture-guard/SKILL.md before edits that affect imports, file layout, shared APIs, runtime adapters, Tauri/HTTP boundaries, Rust capabilities, storage, providers, import/export, or cross-feature behavior.
• Chat, roleplay, and game remain separate mode owners.
• Fix root causes; do not add fake success, silent catches, broad fallbacks, or UI-only guards over broken contracts.
• Do not self-name AI/tool/provider authorship in branch names, commit subjects or labels, PR titles or bodies, issue text, trailers, or release notes. Use task, owner, or problem names only. Avoid names like codex/*, claude-*, ai:, Codex:, Generated by, or AI co-author trailers. Product terms are allowed when they describe De-Koi behavior, compatibility behavior, feature names, file paths, data fields, or user-visible app output; examples include agent, bot-browser, and model-produced chat/message data. Guard checks should reject explicit authorship phrases, not bare domain words.

Before Architecture-Sensitive Edits

• Name the owner/lane before editing: UI feature, TypeScript engine layer, shared API runtime adapter, embedded Tauri command, hostable HTTP dispatch, Rust capability, or docs/tooling.
• Decide whether skills/de-koi-architecture-guard/SKILL.md is required. It is required before edits touching imports, file layout, shared APIs, runtime adapters, Tauri/HTTP boundaries, Rust capabilities, storage, providers, import/export, or cross-feature behavior.
• If the guard is required, load it before editing and keep its owner/import/HTTP-pipeline checklist in force.
• State the matching proof command up front, usually pnpm check:architecture for imports, shared API wrappers, remote-runtime dispatch, or Rust structure changes.
• Prefer rtk for shell commands to reduce output, but rerun the raw command when the wrapper cannot locate the tool or obscures the needed failure.

Credit And Workflow Budget

• Preserve coding quality: use high/adaptive reasoning for code edits, reviews, risky debugging, and architecture. Save credits by avoiding unnecessary agents, browser proof, and PR loops rather than weakening coding reasoning.
• Default to brief unless precision requires detail. Expand for proof, risk, exact external text, approval gates, repo boundaries, or user-facing tone.
• Ordinary bugfix language means local fix and verification by default. Commit, push, draft PR creation, Bunny Review, CI polling, ready marking, and merge require an explicit shipping request such as "ship it", "open a PR", "push this", or "ready for review".
• For shipping, prefer gh-authenticated HTTPS publishing over raw SSH pushes. If an SSH remote push fails, use the authenticated GitHub CLI path, such as gh auth setup-git followed by an HTTPS git push to origin.
• Use the tiny local bug path for narrow, low-risk, machine-provable fixes: no full ledger by default, just a short claim/proof/validation/files/risk/vault receipt. Escalate to the full workflow as soon as the bug is nontrivial, PR-affecting, cross-boundary, storage/import/export/prompt/provider/security-sensitive, browser-evidence-dependent, or uncertain.
• Before local bugfix edits, name only the cheap gate: core claim, likely owner/lane, risk level, and proof target. Broaden the gate only after a hypothesis is falsified or a risk boundary appears.
• Use the cheapest proof that proves the claim. Prefer static inspection, existing test output, temporary uncommitted tests or harnesses, route/module repros, or jsdom/component proof before Playwright; use browser proof when visual layout, interaction, routing, responsive behavior, screenshots, console/network behavior, or browser-only behavior is the claim.
• Proof is session evidence, not permission to add durable test artifacts by reflex.
• Temporary tests and harnesses are allowed when they stay local and uncommitted.
• Cite their command output or resulting observation instead of submitting the artifacts.
• New committed test artifacts are allowed only when at least one condition applies:
  • A maintainer explicitly asks for tests.
  • The change fixes a known regression that needs a small focused guard.
  • The behavior is risky and easy to break silently.
  • The touched area already has a nearby narrow/stable test pattern that is cheaper than repeated manual proof.
• Before adding a durable test artifact, state Durable test rationale with:
  • The regression or risky invariant.
  • Why existing proof is insufficient.
  • Why this test is narrow.
• Prefer the smallest stable test near the owner:
  • Pure helper test.
  • Focused integration test.
  • Component test.
  • Browser/e2e only when browser behavior is the claim.
• Do not add broad fixture suites, snapshots, large e2e tests, or Rust inline tests merely to satisfy proof wording.
• When available, keep workflow-health.mjs for nontrivial De-Koi work, PR work, issue selection, and risky workflow changes. Do not spend it on a tiny one-file local bug unless repo policy or visible risk requires it.

Verification

Run checks that match the change:

• TypeScript/UI/engine: pnpm typecheck
• Build/import graph/bundling: pnpm build
• Rust commands/capabilities/provider transport/hostable runtime: cargo check --manifest-path src-tauri/Cargo.toml
• Docs/skills/agent guidance: pnpm check:docs
• Architecture/import rules: pnpm check:architecture
• PR boundary/ready-for-review: pnpm check (includes a warning-only unused-code report)

Ordinary local bugfixes should run the focused proof and matching lane check. Do not turn every "fix the bug" request into full pnpm check; run full pnpm check when the work becomes PR/shipping/ready-for-review, risky, cross-lane, or otherwise needs the full baseline.

For code changes, final responses must include behavior changed, primary files/modules touched, impact/dependent areas reviewed, verification, and remaining risk.

Deki-senpai Codebase Agent

• Deki-senpai is a codebase-research agent, not a static knowledge-base bot. For De-Koi implementation questions, she should inspect the current repository through her code search/read tools before answering.
• When adding, moving, or deleting a durable feature area, update this section in the same change so Deki-senpai's map stays current.
• When a user asks for app customization, Deki-senpai should prefer creating an extension or custom agent record before editing core source. If core source edits are needed, use narrow exact-match edits and keep the same architecture boundaries listed above.
• Deki-senpai must not read secrets, private chat transcripts, generated dependency/build output, or files outside the De-Koi repository.
• User-facing feature discovery lives in src/features/shell/discovery; keep its registry current when adding or changing discoverable product behavior.

Current Map

• src/app: React bootstrap, shell layout, app providers, startup effects, top bars, sidebars, and panel composition.
• src/features/shell/deki: Deki-senpai's standalone assistant UI surface.
• src/features/shell/discovery: In-app Discover guide, feature metadata registry, search/filter helpers, and discoverability action routing.
• src/features/shell/plugins: Bundled opt-in core module registry, settings UI, React Query hooks, runtime contribution mounting, and the ME Notes chat notepad module.
• src/engine/deki: TypeScript request/response contract for the Deki-senpai entrypoint.
• src-tauri/src/commands/storage/deki.rs and src-tauri/src/commands/storage/deki/*: Privileged Deki-senpai agent execution, tool definitions, codebase search/read/edit access, scoped canonical character-memory and approved chat-memory read/edit access, scoped chat-read access, consent-gated web research/page reads, and extension/custom-agent creation.
• src/shared/api/deki-api.ts: Focused frontend runtime wrapper for the Deki-senpai command.
• src/shared/api/local-sidecar-api.ts: Focused frontend runtime wrapper for Local Model sidecar status, config, runtime/model downloads, process control, and smoke tests.
• src/shared/api/plugin-memory-api.ts: Focused frontend wrapper for namespaced plugin memory stored in the plugin-memory collection and routed through embedded or remote runtime storage.
• src/engine: React-free product behavior and mode orchestration.
• src/features: React UI packages. Shell tools live in src/features/shell, catalog/resource editors live in src/features/catalog, mode surfaces live in src/features/modes, shared runtime UI lives in src/features/runtime.
• src/features/catalog/sprites: Shared catalog sprite query keys, types, and React Query hooks used by character and persona sprite editors plus runtime sprite consumers.
• src/features/catalog/library-folders: Shared durable library-folder hooks for organizing lorebooks and prompt presets.
• src/features/catalog/regex-scripts: Neutral catalog owner for regex script listing, editor routes, storage hooks, scoped filtering, and chat/game runtime application hooks.
• src/features/catalog/memory-maintenance: Shared cleanup review UI, catalog-edge LLM/API binding, chat and canonical memory adapters, and preview/apply/undo workflow used by the chat Memory Console and Character Memories tab.
• src/features/catalog/knowledge, src/engine/generation/epistemic-access.ts, and src-tauri/src/commands/storage/knowledge_edges.rs: Reusable "Who knows this?" editor, engine-owned Roleplay epistemic resolver, and profile-scoped knowledge-edge persistence/lifecycle. Canonical memory text remains owned by canonical-memories; edges only govern holder access and stance.
• src/engine/generation/story-projections.ts, story-consolidation-queue.ts, and story-continuity-context.ts: Roleplay episode/arc boundaries, deterministic background consolidation, and the independent bounded Story Continuity prompt selector.
• src/engine/modes/roleplay/continuity-director, src/shared/api/roleplay-continuity-director-api.ts, and src/features/modes/roleplay/components/RoleplayContinuityDirectorModal.tsx: User-visible Roleplay arc/thread/beat planning, metadata persistence, guarded model refresh, approved-beat prompt projection, and the Roleplay-owned editor. This is not a hidden agent or canonical-memory writer.
• src/features/modes/shared/chat-ui/components/settings/StoryContinuityModal.tsx and src/shared/api/story-continuity-api.ts: Story inspection/actions UI and its focused embedded/remote-capable adapter.
• src-tauri/src/commands/storage/canonical_memory.rs: Canonical story overlap enforcement, supersession cascades, and source edit/delete invalidation alongside ordinary canonical-memory persistence.
• src/shared/api: Embedded Tauri and hostable runtime wrappers. Feature code should call these wrappers instead of raw Tauri or raw remote-runtime fetch.
• src-tauri: Rust command facades, hostable runtime dispatch, storage, LLM/provider transport, assets, imports, integrations, and other privileged capabilities.
• src-tauri/src/commands/storage/sidecar.rs: Thin Tauri/AppState adapter for Local Model sidecar commands and constants.
• src-tauri/crates/sidecar: Local Model sidecar capability implementation, including config, curated GGUF/runtime downloader, loopback process management, synthetic sidecar:local connection materialization, and smoke-test helpers. The Tauri command module stays as the app-state adapter.
• docs/uml/Refactor: PlantUML architecture diagrams for current refactor-era boundaries, hotspots, and decision context; consult these for architecture-sensitive changes. The Refactor name reflects De-Koi's origin as a Marinara Engine refactor.
• public/koi-mark.svg, public/koi-mark-192.png, public/koi-mark-512.png, and public/koi-bg.svg: De-Koi brand and pond marks used by the shell, Deki pond, onboarding helpers, notifications, and app metadata.
• .github/workflows/bunny-review.yml, .github/workflows/bunny-review-auto.yml, .github/workflows/bunny-review-command.yml, .github/bunny-review: Bunny Review PR comment automation, trusted auto and slash-command dispatchers, review packet builder, CI dependencies, path rules, and model reviewer prompt.
• skills/frontend-design: Repo-local frontend concept, layout, visual direction, and first-pass UI implementation workflow that pairs with Impeccable.
• skills/impeccable: Repo-local frontend design, critique, polish, accessibility, responsive, and live-iteration workflow for UI craft passes.
• skills/bunny-style-review: Repo-local branch and PR review workflow for failure-path review and actionable nitpicks.
• skills/de-koi-bugfix-discipline: Root-cause bugfix and feedback-loop-first diagnosis workflow for regressions, failing checks, storage, provider, import/export, generation, mode, and runtime bugs.
• skills/de-koi-architecture-guard: Architecture guardrails for placement, import direction, and remote-capable command routing.
• skills/de-koi-agent-workflow: Agent workflow references, source maps, handoff formats, and verification discipline.
• skills/tdd: Behavior-first De-Koi red-green-refactor workflow using public interfaces and durable-test rationale.
• skills/prototype: Throwaway De-Koi logic, state-model, API-shape, and UI-layout prototype workflow.
• skills/improve-codebase-architecture: Module/interface deepening workflow for locality, leverage, testability, and safe refactor candidates.
• skills/to-issues: Vertical-slice GitHub issue drafting workflow for plans, PRDs, parity targets, and feature ideas.
• skills/to-prd: PRD-style GitHub issue drafting workflow for feature requirements, implementation decisions, and testing decisions.
• skills/grill-with-docs: Plan interrogation and durable decision capture workflow grounded in De-Koi docs and architecture rules.