Dev

.codex/environments/environment.toml

@@ -0,0 +1,6 @@
+# THIS IS AUTOGENERATED. DO NOT EDIT MANUALLY
+version = 1
+name = "TaleSpinner_v1"
+
+[setup]
+script = "yarn install:all"

AGENTS.md

@@ -1,99 +1,134 @@
 # AGENTS.md - TaleSpinner
-Purpose: repository-specific instructions for Codex agents.
-(Назначение: правила работы агента именно в этом репозитории.)
 
-## Quick Commands (run from repo root)
-- Install deps: `yarn install:all` and `yarn install:docs`
-- Dev (server + web): `yarn dev`
-- Dev (docs): `yarn docs:dev`
-- Build all app parts: `yarn build`
+Repository contract for coding agents working in this repo.
+Keep this file outcome-first: preserve the project architecture, make the requested change safely, validate what changed, and stop when the user's goal is handled.
+
+## Project Identity
+- TaleSpinner is a local LLM application for storytelling, roleplay, and multi-agent scenario building.
+- The product is built around isolated profiles, chats and branches, world info, instructions, operation pipelines, and optional RAG flows.
+- The goal is not "one big prompt". The goal is a reproducible, controllable LLM workflow with clean context boundaries.
+
+## Stack And Commands
+- Monorepo: `server` (Node.js + Express + TypeScript), `web` (Vite + React + TypeScript + Effector + Mantine), `docs` (Docusaurus), `shared` (shared contracts and utils), `data` (runtime data).
+- Package manager: Yarn Classic 1.x only. Never switch a task to npm or pnpm.
+- Docs require Node `>=20`.
+- Install app deps: `yarn install:all`
+- Install docs deps: `yarn install:docs`
+- Run app: `yarn dev`
+- Run docs: `yarn docs:dev`
+- Build app: `yarn build`
 - Build docs: `yarn docs:build`
-
-## Stack Snapshot
-- Monorepo: `server` (Node.js + Express + TypeScript), `web` (Vite + React + TypeScript + Effector + Mantine), `docs` (Docusaurus), `shared` (shared TS contracts).
-- Package manager: Yarn Classic (1.x). Do not switch to npm/pnpm in tasks.
-- Runtime note: docs require Node >= 20 (`docs/package.json` engines).
+- Backend checks: `yarn typecheck:server`, `yarn lint:server`, `yarn --cwd server test`, `yarn build:server`
+- Frontend checks: `yarn typecheck:web`, `yarn lint:web`, `yarn build:web`
+- Higher-level checks: `yarn verify:server`, `yarn verify:web`, `yarn docs:check`, `yarn docs:generate:api`
 
 ## Repo Map
-- Backend entrypoint: `server/src/index.ts`
-- API registry: `server/src/api/_routes_.ts`
-- Frontend entrypoint: `web/src/App.tsx`, bootstrap `web/src/main.tsx`
-- Frontend state: `web/src/model/*`
-- Docs RU: `docs/docs/**`
-- Docs EN: `docs/i18n/en/docusaurus-plugin-content-docs/current/**`
-- Shared contracts: `shared/**`
-- Legacy reference only: `server/src/legacy/**`, `web/src/legacy/**`
+- `server/src/index.ts`: backend entrypoint.
+- `server/src/api/_routes_.ts`: API route registry.
+- `server/src/application/**`: use-cases and application orchestration.
+- `server/src/services/**`: domain services and repositories.
+- `server/src/core/**`: shared backend infrastructure, middleware, gateway, factories, errors, logging.
+- `server/src/core/llm-gateway/**`: LLM provider gateway and adapter layer.
+- `server/src/db/schema/**`: database schema.
+- `web/src/main.tsx` and `web/src/App.tsx`: frontend bootstrap.
+- `web/src/model/**`: default home for frontend business state.
+- `web/src/features/**`: UI features.
+- `web/src/api/**`: frontend API clients.
+- `web/src/ui/**`: shared UI and form primitives.
+- `web/src/i18n/**`: localization setup and RU/EN resources.
+- `shared/**`: source of truth for cross-layer contracts.
+- `docs/docs/**`: RU docs.
+- `docs/i18n/en/docusaurus-plugin-content-docs/current/**`: EN docs.
+- `server/src/legacy/**` and `web/src/legacy/**`: reference only. Do not edit unless the task explicitly requires legacy migration.
 
 ## Working Rules
-- Keep changes scoped to the user request. No opportunistic refactors.
-- Prefer `rg` / `rg --files` for search.
-- Before changing code, inspect existing local patterns in neighboring files.
-- Do not edit `legacy` folders unless the task explicitly asks for legacy migration.
-- Never expose secrets or token values in output.
-- Keep code comments in English when adding comments.
-
-## Worktree Startup Rule
-- If current repo folder name starts with `TaleSpinner_` and is not `TaleSpinner_v1`, treat it as a git worktree for tasks.
-- At the start of each new task in such worktree:
+- Before edits, inspect the smallest relevant slice of neighboring implementation, tests, contracts, and docs needed to avoid breaking local patterns.
+- Keep changes scoped to the user's request. Avoid opportunistic refactors and unrelated formatting churn.
+- Prefer `rg` and `rg --files` for search when available.
+- Preserve existing architecture. Add abstractions only when they remove real complexity or match established local patterns.
+- If a touched production file is already oversized, extract the concern you are modifying instead of adding more logic to it.
+- Use explicit domain names, narrow types, small helpers, and flat control flow.
+- Do not leave dead branches, commented-out code, placeholder TODO logic, or temporary debug flows in final changes.
+- Code comments must be in English.
+
+## Size Guidelines
+- Production files should stay near or below 300 lines and must not exceed 400 lines without a strong local reason.
+- Functions should stay near or below 30 logical lines and must not exceed 50 lines.
+- React components should stay near or below 150 lines and must not exceed 200 lines.
+- Generated files, translation dictionaries, migrations, fixtures, and exhaustive tests are exempt.
+
+## Backend
+- Routes are HTTP wiring: parse, validate, call the application/service layer, and map the response.
+- Business rules belong in use-cases or services, not Express handlers.
+- Persistence belongs in repository-style modules.
+- LLM provider access goes through `server/src/core/llm-gateway/**` or established service abstractions.
+- Validate inputs at the edge with existing validation patterns such as `zod`, `validate`, and route schemas.
+- Keep request/response flow typed end to end. Avoid `any`; if a dynamic boundary requires it, keep it local and justified.
+- Use structured error handling. Do not swallow errors.
+- Never expose secrets, token values, encryption keys, cookies, raw auth headers, or env-backed credentials in code, logs, screenshots, tests, or reports.
+- Never log raw request bodies that may contain secrets, tokens, or untrusted large payloads.
+- Treat user markdown, HTML, imported cards, templates, and external provider payloads as untrusted input.
+
+## Frontend
+- Effector is the default state layer for app state, business state, async flows, and cross-component coordination.
+- Business logic belongs in `web/src/model/**`, domain utilities, or clearly scoped feature-model modules.
+- React components should stay focused on presentation and local interaction wiring.
+- `useState` is for leaf-local ephemeral UI state such as disclosures, local tabs, and transient modals.
+- Use `useUnit` for subscribing to Effector stores and binding events/effects in React.
+- Prefer declarative Effector flows with `sample`, events, stores, and effects. Keep `.watch` for debug or narrow side-effect bridges.
+- Forms should use `react-hook-form` and shared primitives from `web/src/ui/form-components/**` when they fit.
+- Keep form subscriptions narrow. Isolate validation, serialization, and submission mapping from presentation.
+- User-facing UI changes must be responsive for phone, tablet, and desktop.
+- Inputs, buttons, icon buttons, menus, tabs, and dialogs need accessible labels and predictable keyboard behavior.
+- Include empty, loading, error, and disabled states when the feature can reach them.
+- Avoid unnecessary rerenders in heavy panels, message lists, editors, and forms.
+
+## Localization
+- All user-facing text belongs in localization resources, not hardcoded in components, stores, helpers, or API mappers.
+- Update Russian and English resources together.
+- Tests, internal debug-only output, and truly non-user-facing diagnostics may use inline text.
+
+## Shared Contracts
+- Shared request/response shapes that matter to both backend and frontend belong in `shared/**`.
+- Do not duplicate shared shapes in `server` and `web`.
+- Treat shared contract changes as public interface changes inside the repo.
+- Validate contract changes in both app layers and update docs when the behavior is externally visible.
+
+## Docs
+- Touch docs only when the task explicitly requires docs work or the code change would otherwise leave affected docs knowingly stale.
+- Keep RU and EN docs structurally aligned.
+- If docs are touched and API routes or shared contract surface changed, run `yarn docs:generate:api` before `yarn docs:check`.
+
+## Testing And Verification
+- For backend/frontend behavior changes, write or update the most relevant failing test first, make it pass, then refactor.
+- Pure logic gets unit tests.
+- Service orchestration, repositories, route contracts, complex state transitions, and regression-prone UI flows get integration-style coverage.
+- For docs-only, config-only, formatting-only, or mechanical changes where tests add no signal, state why targeted tests were not needed.
+- After changes, run the narrowest validation that proves the touched behavior:
+  - targeted tests for changed behavior
+  - type checks or lint checks for affected packages
+  - build checks when packaging, shared contracts, or bundling may be affected
+  - a smoke test when full validation is too expensive
+- Run the full relevant suite before claiming broad readiness, after cross-layer changes, or when the blast radius is unclear.
+- If validation cannot be run, explain why and name the next best check.
+
+## Worktree Startup
+- If the current repo folder name starts with `TaleSpinner_` and is not exactly `TaleSpinner_v1`, treat it as a git worktree.
+- At the start of a new task in such a worktree:
   - run `git fetch origin dev`
-  - if current branch is `dev`, `main`, or detached `HEAD`, create and switch to a task branch from `origin/dev` before edits
-  - run `sync-db-from-main.bat --no-extra --no-pause` to refresh local DB from the main folder
-
-## Area-Specific Guidance
-
-### Backend (`server/**`)
-- Follow existing API style in `server/src/api/*` and shared middleware patterns (`asyncHandler`, `errorHandler`, `validate` where applicable).
-- For new or changed endpoints, prefer typed request/response flow and avoid `any`.
-- If endpoint behavior changes, ensure API docs inventory can be regenerated.
-
-Required checks after backend changes:
-- `yarn typecheck:server`
-- Run focused tests in server when logic is touched:
-  - all tests: `yarn --cwd server test`
-  - or targeted: `yarn --cwd server test -- <name-pattern>`
-
-### Frontend (`web/**`)
-- Respect FSD-style boundaries already used in repo (`features`, `model`, `ui`, `api`, `utils`).
-- Keep business logic in `model/*` or utilities, not large UI handlers.
-- Reuse existing aliases and local conventions.
-
-Required checks after frontend changes:
-- `yarn typecheck:web`
-- If build/tooling/entrypoint changed: `yarn build:web`
-
-### Docs (`docs/**`)
-- Docs are code-adjacent and must match current behavior.
-- Keep RU/EN structure parity.
-- If API routes changed: regenerate API endpoints docs.
-
-Required checks after docs or API-doc changes:
-- `yarn docs:generate:api` (only when API surface changed)
-- `yarn docs:check`
-
-### Shared (`shared/**`)
-- Any contract change must be validated in both app layers.
-
-Required checks after shared changes:
-- `yarn typecheck:server`
-- `yarn typecheck:web`
-
-## Definition of Done
-- Requested behavior implemented and consistent with neighboring architecture.
-- Required scope checks passed.
-- If docs touched, RU/EN parity preserved.
-- Final report includes:
-  - changed files
-  - why change was made
-  - commands executed
-  - test/check results
-
-## Safety & Data Handling
-- Treat `server/data/config/*` and env-backed credentials as sensitive.
-- Do not add endpoints that return raw secrets.
-- Keep static serving restricted to intended public media paths.
-- Treat user-provided markdown/HTML as untrusted content.
-
-## Instruction Hygiene (for future edits of this file)
-- Keep this file concise, concrete, and command-first.
-- Prefer actionable rules over broad style essays.
-- If rules become large, split by subdirectories with additional local `AGENTS.md` files.
+  - if the current branch is `dev`, `main`, or detached `HEAD`, create and switch to a task branch from `origin/dev`
+  - run `sync-db-from-main.bat --no-extra --no-pause`
+
+## Definition Of Done
+- The requested behavior is implemented in the correct layer and follows neighboring architecture.
+- Relevant tests and checks pass, or any skipped validation is explicitly justified.
+- Security, file-access, and logging boundaries are preserved.
+- RU/EN localization parity is preserved for user-facing text.
+- RU/EN docs parity is preserved when docs are touched.
+- The final report includes changed files, why the change was made, commands executed, and test/check results.
+
+## Stop Rules
+- Ask a narrow clarification only when missing information would materially change the implementation or create meaningful risk.
+- Stop searching once the core request can be answered or implemented with enough local evidence.
+- Stop editing once the requested behavior and Definition of Done are satisfied.
+- If a required change would violate these rules, report the conflict before proceeding.