### Install and Start Covel Dev Server

Source: https://context7.com/ackness/covel/llms.txt

Installs dependencies, copies example configuration files, and starts the development server. Supports different storage backends like SQLite and PostgreSQL.

```bash
pnpm install
cp llm.toml.example llm.toml
cp .env.llm.example .env.llm
pnpm dev          # web :5173 + server :3001
pnpm dev:server   # server only
STORE_BACKEND=pg DATABASE_URL=postgresql://covel:pass@localhost:5432/covel pnpm dev:server
```

--------------------------------

### Setup Development Environment

Source: https://github.com/ackness/covel/blob/main/docs/CONTRIBUTING.en.md

Install dependencies, configure LLM settings, and start the development server.

```bash
pnpm install
cp llm.toml.example llm.toml   # configure LLM slots
cp .env.llm.example .env.llm   # fill in API keys
pnpm dev                       # start frontend + backend
```

--------------------------------

### Install and Run Covel from Source

Source: https://github.com/ackness/covel/blob/main/README.md

Install dependencies, configure LLM settings, and start the development server. This setup is for running Covel from its source code.

```bash
pnpm install
cp llm.toml.example llm.toml        # model IDs and endpoints
cp .env.llm.example .env.llm        # provider API keys
pnpm dev                            # web :5173 + server :3001 (SQLite)
```

--------------------------------

### Install and Develop Covel

Source: https://github.com/ackness/covel/blob/main/CLAUDE.md

Commands for installing dependencies and starting the development server for web and server components. Includes options for different database backends.

```bash
pnpm install
pnpm dev              # web (5173) + server (3001), SqliteStore (default, ./data/covel.db)
pnpm dev:web          # web only
pnpm dev:server       # server only (SqliteStore default; STORE_BACKEND=memory for ephemeral)
pnpm dev:pg           # server only, STORE_BACKEND=pg (needs pnpm db:up first)
```

--------------------------------

### Install and Run Covel Server

Source: https://github.com/ackness/covel/blob/main/docs/reference/api.md

Install project dependencies and start the development server. SQLite is used as the default backend, and the server runs on port 3001.

```bash
pnpm install

pnpm dev:server
```

--------------------------------

### Start Backend Service Pointing to aimock

Source: https://github.com/ackness/covel/blob/main/docs/guide/e2e-testing.md

Configure your backend service to use aimock as the LLM endpoint. Two methods are provided: using environment variables or a full development environment setup.

```bash
# 方式1: 使用环境变量覆盖
export COVEL_STORY_BASE_URL=http://127.0.0.1:4010/v1
export COVEL_PLUGIN_BASE_URL=http://127.0.0.1:4011/v1
pnpm dev:server

# 方式2: 完整开发环境（包含前端）
COVEL_STORY_BASE_URL=http://127.0.0.1:4010/v1 \
COVEL_PLUGIN_BASE_URL=http://127.0.0.1:4011/v1 \
pnpm dev
```

--------------------------------

### TOML Configuration Example

Source: https://github.com/ackness/covel/blob/main/docs/guide/desktop-config.md

Example TOML configuration for setting data directory paths and logging parameters. Changes require an application restart and do not migrate existing data.

```toml
[paths]
# 数据目录。相对路径相对于本文件所在目录；绝对路径直接使用。
# 默认：~/.covel/data
# data_root = "/Volumes/External/covel-data"

[logging]
# 单个日志文件上限（MB），超过后轮转
max_size_mb = 10
# 保留的轮转文件数，超出后丢弃最旧一份。总磁盘占用 ≈ max_size_mb × max_files
max_files   = 10
```

--------------------------------

### Start aimock Containers

Source: https://github.com/ackness/covel/blob/main/docs/guide/e2e-testing.md

Use this command to start the aimock service in recording and replay mode. Verify the service status using curl commands.

```bash
# 启动 aimock 服务（录制+回放模式）
docker compose -f docker/docker-compose.mock.yml up -d

# 验证服务状态
curl http://localhost:4010/health  # story LLM (DeepSeek)
curl http://localhost:4011/health  # plugin LLM (DashScope)
```

--------------------------------

### Covel Plugin Configuration Example

Source: https://github.com/ackness/covel/blob/main/README.md

Example frontmatter for a Covel plugin. It defines the plugin's name, priority, model type, trigger conditions, and available tools.

```yaml
---
name: my-plugin/main
priority: 500
model: plugin
trigger: { type: scheduled, interval: 1 }
tools:
  builtin: [create-form, plugin-data-set]
---
You are an XXX agent. On this turn you need to…
```

--------------------------------

### Configuration File: config.toml

Source: https://github.com/ackness/covel/blob/main/docs/guide/desktop-config.en.md

Example TOML configuration for setting the data directory and logging parameters. Restart the application after making changes.

```toml
[paths]
# Data directory. Relative paths resolve against this file's directory;
absolute paths are used as-is. Default: ~/.covel/data
# data_root = "/Volumes/External/covel-data"

[logging]
# Single log-file cap (MB). Rolls over once exceeded.
max_size_mb = 10
# Retained rotated files. Oldest is dropped past this cap.
# Total disk usage ≈ max_size_mb × max_files.
max_files   = 10

```

--------------------------------

### Install Plugin Test Dependencies

Source: https://github.com/ackness/covel/blob/main/docs/guide/plugin-authoring-agent.md

Add `@covel/plugin-loader`, `@covel/plugin-test-utils`, and `vitest` to your devDependencies to enable plugin testing.

```json
{
  "devDependencies": {
    "@covel/plugin-loader": "workspace:*",
    "@covel/plugin-test-utils": "workspace:*",
    "vitest": "^4.1.2"
  }
}
```

--------------------------------

### Install Frozen Lockfile

Source: https://github.com/ackness/covel/blob/main/docs/refactor/2026-05-09_13-05_long-file-restructure.md

Installs dependencies using the frozen-lockfile strategy.

```bash
mise exec -- pnpm install --frozen-lockfile
```

--------------------------------

### Example 'create-notification' Usage

Source: https://github.com/ackness/covel/blob/main/docs/guide/plugin-authoring-zero-code.md

Provides an example of how to use 'create-notification' to inform players about game events, such as unlocking a new codex entry. It specifies the notification level, title, and message.

```markdown
### create-notification

每解锁一个新条目，发一条通知。使用 `success` 级别，标题格式："📖 发现新知识：{title}"
```

--------------------------------

### Plugin Data Set Tool Call Example

Source: https://github.com/ackness/covel/blob/main/templates/plugin-multi-runtime/runtimes/summarizer/PLUGIN.md

Example of how to call the `plugin-data-set` tool to store a summary. The `namespace` is 'messages', the `key` is 'summary-' followed by a timestamp, and the `value` is a JSON object containing the role, text summary, and creation timestamp.

```plaintext
| 参数        | 值                                                                                     |
| ----------- | -------------------------------------------------------------------------------------- |
| `namespace` | `messages`                                                                             |
| `key`       | `summary-` 加当前时间戳的 base36，例如 `summary-lz0abc`                                |
| `value`     | `{ "role": "summary", "text": "<你的 100 字摘要>", "createdAt": "<ISO 8601 时间戳>" }` |

```

--------------------------------

### Sign Windows Executable

Source: https://github.com/ackness/covel/blob/main/apps/desktop/PACKAGING.md

Use PowerShell to get the Authenticode signature of the Covel-Setup executable. This is a crucial step for Windows application security and trust.

```powershell
Get-AuthenticodeSignature release\Covel-Setup-*.exe
```

--------------------------------

### World Configuration with Plugin Dependencies (YAML)

Source: https://github.com/ackness/covel/blob/main/docs/reference/world-data.md

Example of a world.yaml file specifying plugin relationships using 'recommendedPlugins' and 'pluginPolicy'. It also declares the path to the world data file.

```yaml
recommendedPlugins:
  - social-sim
pluginPolicy:
  recommendedPlugins:
    - social-sim
worldData: data/world.data.yaml
```

--------------------------------

### Focus on a Specific Plugin with Limited Turns

Source: https://github.com/ackness/covel/blob/main/docs/guide/e2e-plugin-verify.md

Tests the 'guide' plugin specifically for 2 turns using local LLM mock and default slot. This helps isolate issues within a single plugin.

```bash
npx tsx --env-file=.env --env-file=.env.llm 
  scripts/e2e-plugin-verify.ts --plugin guide --turns 2
```

--------------------------------

### Plugin Data Record Example (YAML)

Source: https://github.com/ackness/covel/blob/main/docs/reference/world-data.md

An example of a data record for a plugin, formatted as a YAML array. Each item represents a data object with fields like id, from, to, type, and score.

```yaml
- id: mio-rin
  from: kamishiro-mio
  to: asakura-rin
  type: clubmate
  score: 42
```

--------------------------------

### Example: Minimal Event Tracking Plugin

Source: https://github.com/ackness/covel/blob/main/docs/guide/plugin-authoring-zero-code.md

A concise example of a plugin designed to track important events in a narrative. It defines the plugin's name, description, type, priority, model, and trigger, along with prompt instructions for the LLM.

```markdown
---
name: my-event-tracker
description: 追踪故事中发生的重要事件
pluginType: plugin
priority: 650
model: plugin
trigger:
  type: auto
---

你是一个事件追踪系统。分析每轮叙事，识别重要事件。

## 当前叙事

{{ player.message }}

## 你的任务

1. 阅读叙事内容
2. 判断是否有重要事件发生（战斗、发现、社交等）
3. 如果有，输出 JSON 格式的事件摘要
4. 如果没有重要事件，输出空 JSON `{}`

## 硬规则

- 只记录叙事中**明确发生**的事件
- 每轮最多 3 个事件
- 不推测、不编造
```

--------------------------------

### Electron Development and Build Commands

Source: https://github.com/ackness/covel/blob/main/CLAUDE.md

Commands for running the Electron development shell, building platform installers, and creating desktop builds.

```bash
pnpm dev:electron
```

```bash
pnpm build:electron
```

```bash
pnpm build:desktop
```

--------------------------------

### Manage Covel Database

Source: https://github.com/ackness/covel/blob/main/CLAUDE.md

Docker commands for managing the project's database, including starting, stopping, generating, migrating, and accessing the database studio.

```bash
# Database (Docker)
pnpm db:up / db:down / db:generate / db:migrate / db:studio
```

--------------------------------

### Create One-Click E2E Test Script

Source: https://github.com/ackness/covel/blob/main/docs/guide/e2e-testing.md

A bash script to automate the process of starting aimock, backend services, and running E2E tests. Supports both recording and pure replay modes.

```bash
#!/bin/bash
set -e

REPLAY_MODE="${1:-}"

# 启动 aimock
echo "🚀 Starting aimock containers..."
docker compose -f docker/docker-compose.mock.yml up -d

# 等待服务就绪
echo "⏳ Waiting for aimock to be ready..."
until curl -sf http://localhost:4010/health > /dev/null 2>&1; do sleep 1; done
until curl -sf http://localhost:4011/health > /dev/null 2>&1; do sleep 1; done
echo "✅ aimock ready!"

# 启动后端服务
echo "🚀 Starting backend server..."
export COVEL_STORY_BASE_URL=http://127.0.0.1:4010/v1
export COVEL_PLUGIN_BASE_URL=http://127.0.0.1:4011/v1
pnpm dev:server &
SERVER_PID=$!

# 等待后端就绪
echo "⏳ Waiting for backend to be ready..."
until curl -sf http://localhost:3001/api/health > /dev/null 2>&1; do sleep 1; done
echo "✅ Backend ready!"

# 运行测试
echo "🧪 Running E2E tests..."
if [ "$REPLAY_MODE" = "--replay" ]; then
    export AIMOCK_REPLAY_ONLY=1
    echo "Mode: REPLAY ONLY"
else
    echo "Mode: RECORD + REPLAY"
fi

npx tsx --env-file=.env --env-file=.env.llm scripts/e2e-plugin-verify.ts

# 清理
kill $SERVER_PID 2>/dev/null || true
echo "✅ Test completed!"

```

--------------------------------

### Plugin Capabilities Example (YAML Frontmatter)

Source: https://github.com/ackness/covel/blob/main/docs/reference/plugins.md

This YAML snippet demonstrates how to declare a plugin's capabilities directly in its frontmatter. This is used for framework-level discovery and functionality mapping.

```yaml
capabilities: [narrative, world-data-provider]
```

--------------------------------

### Docker Full Stack Commands

Source: https://github.com/ackness/covel/blob/main/CLAUDE.md

Manage the Dockerized Covel application stack with commands for building, starting, stopping, and viewing logs.

```bash
pnpm docker:build
```

```bash
pnpm docker:up
```

```bash
pnpm docker:down
```

```bash
pnpm docker:logs
```

--------------------------------

### Plugin Capabilities Example (JSON Response)

Source: https://github.com/ackness/covel/blob/main/docs/reference/plugins.md

This JSON snippet shows how a plugin's capabilities are exposed in the API response. It helps the frontend discover available plugin functionalities.

```json
{
  "id": "world-init",
  "pluginType": "core-plugin",
  "active": true,
  "capabilities": ["world-data-provider"]
}
```

--------------------------------

### Character Management Tools - create/update/list/get-character

Source: https://context7.com/ackness/covel/llms.txt

JSON examples for Covel's framework-level character management tools, including creation with deduplication, shallow merging updates, listing, and retrieving full character attributes.

```json
// create-character
{ "name": "苏婉", "type": "npc", "description": "青萍宗外门首席弟子，冰灵根修士", "fields": { "hp": 100, "level": 5, "lingGen": "冰灵根" } }
// LLM sees: Created npc "苏婉" as char-abc123. — 青萍宗外门首席弟子，冰灵根修士。

// update-character — shallow merge on fields, auto-increments version
{ "id": "char-abc123", "fields": { "hp": 60, "status": "wounded" } }
// LLM sees: Updated npc "苏婉" (char-abc123) → v2.
  hp: 100 → 60
  status: alive → wounded

// list-characters — sorted by interaction frequency then recency
{ "type": "npc" }
// LLM sees: Characters in session (2 total...):
1. 苏婉 [npc] char-abc (v3) — ...
2. 柳娘 [npc] ...

// get-character — full attributes
{ "name": "苏婉" }
// LLM sees: Character: 苏婉 [npc] char-abc123
Description: ...
Version: 3
Attributes:
  hp: 60
  ...
```

--------------------------------

### Example 'create-form' Narrative Template

Source: https://github.com/ackness/covel/blob/main/docs/guide/plugin-authoring-zero-code.md

Demonstrates how a narrativeTemplate in 'create-form' generates dynamic text. User-filled values replace placeholders like {{characterName}} to create a personalized narrative for the next turn.

```markdown
narrativeTemplate: "你的名字叫 {{characterName}}，拥有 {{spiritRoot}} 灵根。"
```

--------------------------------

### Build Desktop Application

Source: https://github.com/ackness/covel/blob/main/docs/refactor/2026-05-09_13-05_long-file-restructure.md

Builds the @covel/desktop package with a timeout of 180 seconds.

```bash
timeout 180s mise exec -- pnpm --filter @covel/desktop build
```

--------------------------------

### Opting out of Transactions via Environment Variable

Source: https://github.com/ackness/covel/blob/main/docs/reference/transactions.md

These examples show how to disable transaction processing by setting the COVEL_COMMIT_TXN_V1 environment variable to '0' or 'false' when starting the server or a specific process.

```bash
COVEL_COMMIT_TXN_V1=0 pnpm dev:server
# or
COVEL_COMMIT_TXN_V1=false pnpm dev:pg
```

--------------------------------

### List Available Plugins

Source: https://github.com/ackness/covel/blob/main/docs/reference/api.md

View all available plugins that can be included when creating a new game session.

```bash
curl http://localhost:3001/api/plugins
```

--------------------------------

### Preflight API Request (HTTP)

Source: https://github.com/ackness/covel/blob/main/docs/reference/world-data.md

Example of an HTTP POST request to the /api/worlds/{world-id}/world-data/preflight endpoint. This is used to perform preflight checks before starting a game, optionally specifying plugins or a session ID.

```http
POST /api/worlds/<world-id>/world-data/preflight
```

--------------------------------

### Regenerate Entry Handler Example

Source: https://context7.com/ackness/covel/llms.txt

Example implementation of the `regenerate-entry` RPC handler.

```javascript
export default async function handler(payload, context) {
  // context: { sessionId, pluginId, action, store }
  const { entryId } = payload;
  const existing = await context.store.getPluginData(
    context.sessionId, context.pluginId, "entries", entryId
  );
  if (!existing) return { error: "Entry not found" };

  // Trigger a runtime to regenerate
  // (handler returns data; complex flows use plugin-rpc runtime-level call)
  return { status: "queued", entryId, message: "Regeneration scheduled" };
}
```

--------------------------------

### Build Covel Desktop Artifacts

Source: https://github.com/ackness/covel/blob/main/apps/desktop/PACKAGING.md

Run this command to build the Covel desktop application, which stages resources for packaging.

```bash
pnpm --filter @covel/desktop build
```

--------------------------------

### Execute Covel Test Runtime Binaries

Source: https://github.com/ackness/covel/blob/main/docs/guide/plugin-testing.md

Provides two methods for running the `covel-test-runtime` binary, suitable for published packages. Use `npx` to execute directly or with the `-p` flag.

```bash
npx @covel/test-runtime my-plugin/my-runtime --payload '{"debug":true}'
```

```bash
npx -p @covel/test-runtime test_runtime my-plugin/my-runtime --payload '{"debug":true}'
```

--------------------------------

### Override Descriptor Example (YAML)

Source: https://github.com/ackness/covel/blob/main/docs/reference/world-data.md

An example of an override descriptor file (world.data.override.yaml). It can define new sources or modify existing ones by specifying properties like path, enabled status, and merge strategy.

```yaml
schemaVersion: 1
sources:
  social-links:
    kind: yaml
    path: data/social/links.yaml
    schema: plugin://social-sim/relationships
    to: plugin:social-sim/relationships
    key: id
    merge: skipExisting
```

--------------------------------

### Basic Plugin Test with Harness

Source: https://github.com/ackness/covel/blob/main/docs/guide/plugin-testing.md

Demonstrates setting up and running a basic plugin test using the `@covel/plugin-test-utils` harness. Imports necessary testing utilities and configures a `MockLLM` for in-process testing.

```typescript
import { describe, it, expect } from "vitest";
import path from "node:path";
import {
  MockLLM,
  createTestHarness,
  makeTurnInput,
} from "@covel/plugin-test-utils";

const PLUGINS_DIR = path.resolve(import.meta.dirname, "../../../plugins");

describe("my-plugin", () => {
  it("runs a turn end-to-end", async () => {
    const llm = new MockLLM({
      defaultResponse: {
        content: "You step into the cavern.",
        toolCalls: [],
        finishReason: "stop",
        usage: { inputTokens: 100, outputTokens: 20 },
      },
    });

    const harness = await createTestHarness({
      pluginsDir: PLUGINS_DIR,
      activePlugins: ["my-plugin"],
      llm,
    });

    const result = await harness.executeTurn("look around");

    expect(result.runtimeResults[0].status).toBe("success");
    expect(llm.calls).toHaveLength(1);
  });
});
```

--------------------------------

### Plugin Runtime Splitting Strategy

Source: https://github.com/ackness/covel/blob/main/docs/guide/plugin-authoring-zero-code.md

Illustrates how to split a plugin into separate 'pre' and 'post' runtimes when a single runtime needs to both read and write to the store, ensuring clear data flow.

```markdown
| 插件        | pre runtime（只读）                           | post runtime（写）                           |
| ----------- | --------------------------------------------- | -------------------------------------------- |
| `npc-graph` | `rag-retriever` (490) — 查图谱注入 npcContext | `extractor` (620) — 基于叙事 upsert 节点和边 |
```

--------------------------------

### Query Endpoints

Source: https://github.com/ackness/covel/blob/main/docs/reference/protocol.md

Read-only data retrieval endpoints using standard REST GET requests.

```APIDOC
## Query Endpoints

### Session List
**Method:** GET
**Endpoint:** `/api/sessions?worldId=`
**Response:** `{ items: SessionRecord[] }`

### Session Details
**Method:** GET
**Endpoint:** `/api/sessions/:id`
**Response:** `SessionRecord`

### Session Snapshot
**Method:** GET
**Endpoint:** `/api/sessions/:id/snapshot`
**Response:** `SessionSnapshot`

### Message List
**Method:** GET
**Endpoint:** `/api/sessions/:id/messages`
**Response:** `MessageRecord[]`

### Character List
**Method:** GET
**Endpoint:** `/api/sessions/:id/characters`
**Response:** `{ items: CharacterRecord[] }`

### Plugin List
**Method:** GET
**Endpoint:** `/api/sessions/:id/plugins`
**Response:** `{ active[], available[] }`

### State Query
**Method:** GET
**Endpoint:** `/api/sessions/:id/state`
**Response:** `{ tables }`

### State Patches
**Method:** GET
**Endpoint:** `/api/sessions/:id/state-patches`
**Response:** `Patch[]`

### Plugin Data
**Method:** GET
**Endpoint:** `/api/sessions/:id/plugin-data/:pluginId/:ns`
**Response:** `{ items[] }`

### World List
**Method:** GET
**Endpoint:** `/api/worlds`
**Response:** `{ items: WorldRecord[] }`

### Execution Trace
**Method:** GET
**Endpoint:** `/api/traces/:sessionId`
**Response:** `{ events[] }`

### Service Health
**Method:** GET
**Endpoint:** `/api/health`
**Response:** `{ status, version, storeBackend }`
```

--------------------------------

### Build and Check Covel

Source: https://github.com/ackness/covel/blob/main/CLAUDE.md

Commands for building the project, linting, running tests (with coverage option), and cleaning build artifacts.

```bash
pnpm build            # build all
pnpm lint             # tsc --noEmit across workspace
pnpm test             # vitest via turbo (cached)
pnpm test:coverage    # + @vitest/coverage-v8
pnpm clean
```

--------------------------------

### List Available Worlds

Source: https://github.com/ackness/covel/blob/main/docs/reference/api.md

Retrieve a list of all available game worlds that can be used to start a new session.

```bash
curl http://localhost:3001/api/worlds
```

--------------------------------

### Discover UI Components with Regex

Source: https://github.com/ackness/covel/blob/main/docs/reference/ui-components.md

Use these grep commands to find UI components in the codebase. The first command searches for component renderers, while the second lists registry entries.

```bash
rg ": ComponentRenderer = |export function createFilterContainer" apps/web/src/lib/catalog.tsx apps/web/src/lib/catalog
```

```bash
rg "^  [A-Z][a-zA-Z]+," apps/web/src/lib/catalog.tsx   # registry entries
```

--------------------------------

### Create New Game Session

Source: https://github.com/ackness/covel/blob/main/docs/reference/api.md

Initiate a new game session with a specified world, locale, and plugins. Remember to note the returned session ID for subsequent requests.

```bash
curl -X POST http://localhost:3001/api/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "worldId": "cloudmere",
    "locale": "zh-CN",
    "plugins": ["pregame", "narrator", "codex"]
  }'
```

--------------------------------

### Preflight World Data Check

Source: https://github.com/ackness/covel/blob/main/docs/reference/world-data.md

Perform a preflight check on world data before starting a game to review planned writes and diagnostics.

```APIDOC
## Preflight World Data Check

Check world data before starting a game.

### Method

```http
POST /api/worlds/<world-id>/world-data/preflight
```

### Parameters

#### Request Body

- **plugins** (array) - Optional - List of plugins to preflight against.
- **sessionId** (string) - Optional - Session ID to preflight against existing session plugins.
```

--------------------------------

### Run Linting and Testing with pnpm

Source: https://github.com/ackness/covel/blob/main/docs/refactor/2026-05-09_13-05_long-file-restructure.md

Execute linting and testing commands for various packages using `pnpm` and `mise exec`. Includes specific package filters and timeouts.

```bash
timeout 120s mise exec -- pnpm --filter @covel/runtime lint
```

```bash
timeout 120s mise exec -- pnpm --dir packages/runtime exec vitest run tests/turn-executor-events.test.ts
```

```bash
timeout 180s mise exec -- pnpm --dir packages/runtime exec vitest run tests/turn-executor-suspend.test.ts tests/turn-executor.test.ts tests/turn-executor-recursive-call.test.ts tests/turn-executor-manual-trigger.test.ts
```

```bash
timeout 180s mise exec -- pnpm --filter @covel/runtime test
```

```bash
timeout 180s mise exec -- pnpm lint
```

```bash
timeout 240s mise exec -- pnpm test
```

```bash
timeout 120s mise exec -- pnpm exec prettier --check ...
```

```bash
timeout 120s mise exec -- pnpm --filter @covel/web lint
```

```bash
timeout 120s mise exec -- pnpm --filter @covel/server lint
```

```bash
timeout 180s mise exec -- pnpm --filter @covel/web exec vitest run src/services/__tests__/api-session-plugins.test.ts src/services/__tests__/api-worlds-approvals.test.ts
```

```bash
timeout 180s mise exec -- pnpm --filter @covel/runtime exec vitest run tests/session-kernel.test.ts tests/session-kernel-txn.test.ts tests/hook-wire-session-kernel.test.ts tests/working-memory-commit.test.ts tests/proposal-source-invariant.test.ts tests/tool-executor-core-plugin-commit.test.ts tests/core-plugin-npc-graph-inject.test.ts
```

```bash
timeout 180s mise exec -- pnpm --filter @covel/server exec vitest run tests/lib/world-data-session-import.test.ts tests/lib/world-data-loader.test.ts
```

```bash
timeout 240s mise exec -- pnpm --filter @covel/web test
```

```bash
timeout 240s mise exec -- pnpm --filter @covel/runtime test
```

```bash
timeout 240s mise exec -- pnpm --filter @covel/server test
```

```bash
timeout 360s mise exec -- pnpm test
```

```bash
timeout 120s mise exec -- pnpm --filter @covel/web exec vitest run src/components/session/__tests__/plugin-metadata.test.tsx src/lib/__tests__/session-plugin-selection.test.ts src/services/__tests__/api-worlds-approvals.test.ts
```

```bash
timeout 120s mise exec -- pnpm exec prettier --check apps/web/src/components/session/session-prep-screen.tsx apps/web/src/components/session/session-prep/*.ts apps/web/src/components/session/session-prep/*.tsx apps/web/src/routes/debug.tsx apps/web/src/routes/debug/*.ts apps/web/src/routes/debug/*.tsx
```

```bash
timeout 240s mise exec -- pnpm --filter @covel/web test
```

```bash
timeout 240s mise exec -- pnpm lint
```

```bash
timeout 360s mise exec -- pnpm test
```

```bash
timeout 120s mise exec -- pnpm --filter @covel/store lint
```

```bash
timeout 180s mise exec -- pnpm --filter @covel/store exec vitest run tests/media-store.test.ts tests/store-factory-env.test.ts
```

```bash
timeout 240s mise exec -- pnpm --filter @covel/store test
```

```bash
timeout 180s mise exec -- pnpm --filter @covel/server exec vitest run tests/api/media.test.ts tests/api/media-cleanup.test.ts
```

```bash
timeout 180s mise exec -- pnpm --filter @covel/store exec vitest run tests/memory-store.test.ts tests/idb-store.test.ts tests/plugin-data-contract-extras.test.ts
```

```bash
timeout 120s mise exec -- pnpm --filter @covel/server lint
```

```bash
timeout 180s mise exec -- pnpm --filter @covel/server exec vitest run tests/api/plugin-flow-routes.test.ts tests/api/ui-specs-session-aware.test.ts tests/api/ui-specs-user-plugins.test.ts tests/api/security-fixes.test.ts
```

```bash
timeout 240s mise exec -- pnpm --filter @covel/server test
```

```bash
timeout 240s mise exec -- pnpm lint
```

```bash
timeout 360s mise exec -- pnpm test
```

```bash
timeout 180s mise exec -- pnpm --filter @covel/desktop build
```

```bash
timeout 240s mise exec -- pnpm lint
```

```bash
timeout 120s mise exec -- pnpm exec prettier --check apps/desktop/src/main.ts apps/desktop/src/env-files.ts apps/desktop/src/network.ts apps/desktop/src/splash-screen.ts apps/desktop/src/startup-errors.ts
```

```bash
timeout 180s mise exec -- pnpm --filter @covel/store exec vitest run tests/sqlite-store.test.ts tests/pg-store.test.ts tests/plugin-data-contract-extras.test.ts
```

```bash
timeout 240s mise exec -- pnpm --filter @covel/store test
```

```bash
timeout 120s mise exec -- pnpm exec prettier --check packages/store/src/sqlite/sqlite-store.ts packages/store/src/sqlite/sqlite-store-values.ts packages/store/src/postgres/pg-store.ts packages/store/src/postgres/pg-store-values.ts
```

```bash
timeout 180s mise exec -- pnpm --filter @covel/store exec vitest run tests/sqlite-store.test.ts tests/pg-store.test.ts
```

--------------------------------

### List Session Characters

Source: https://context7.com/ackness/covel/llms.txt

Retrieve a list of all characters associated with a specific session using a GET request to the /api/sessions/:id/characters endpoint.

```bash
curl http://localhost:3001/api/sessions/cloudmere-a1b2c3d4/characters
```

--------------------------------

### Run Web Linting

Source: https://github.com/ackness/covel/blob/main/docs/refactor/2026-05-09_13-05_long-file-restructure.md

Executes linting checks for the @covel/web package with a timeout of 120 seconds.

```bash
timeout 120s mise exec -- pnpm --filter @covel/web lint
```

--------------------------------

### World Package Manifest - world.yaml

Source: https://context7.com/ackness/covel/llms.txt

Example of a world package manifest file (`world.yaml`) defining world metadata, locales, plugins, and data paths.

```yaml
# worlds/my-world/world.yaml
schemaVersion: "1.0"
id: my-world
name: My Custom World
version: "0.1.0"
summary: A world description shown in the session creation screen.
defaultLocale: en-US
supportedLocales:
  - en-US
  - zh-CN
tags:
  - fantasy
  - adventure
requiredPlugins:
  - pregame
  - world-init
  - char-creator
  - narrator
recommendedPlugins:
  - guide
  - codex
  - npc-graph
excludedPlugins:
  - chat-mode-narrator
pluginPolicy:
  preset: traditional-story
  preferTags:
    - mode:traditional-story
  avoidTags:
    - mode:dialogue
worldData: data/world.data.yaml    # optional: declarative world data import
```

--------------------------------

### Environment Variables for API Keys

Source: https://github.com/ackness/covel/blob/main/docs/guide/desktop-config.md

Example format for storing provider API keys in an environment file. Keys are in KEY=VALUE format and are scanned by the server.

```env
# 一行一个 KEY=VALUE，# 开头是注释
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxx
OPENAI_API_KEY=sk-xxxxxxxxxxxx
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxx
```

--------------------------------

### Plugin and World Package Structure

Source: https://github.com/ackness/covel/blob/main/docs/reference/world-data.md

Illustrates a recommended directory structure for packaging plugins and world data together. Plugins reside in the 'plugins' directory, while world-specific data and assets are in the 'worlds' directory.

```text
my-covel-pack/
├── plugins/
│   └── social-sim/
│       ├── PLUGIN.md
│       └── handler.js
└── worlds/
    └── haruka-social-extra/
        ├── world.yaml
        ├── WORLD.md
        └── data/
            ├── world.data.yaml
            └── social/links.yaml
```

--------------------------------

### Build Windows Artifacts

Source: https://github.com/ackness/covel/blob/main/apps/desktop/PACKAGING.md

Build the Windows version of the Covel desktop application. Ensure the CSC_LINK and CSC_KEY_PASSWORD environment variables are set for code signing.

```bash
CSC_LINK=/path/to/cert.pfx \
CSC_KEY_PASSWORD=... \
  pnpm --filter @covel/desktop dist:win
```

--------------------------------

### Desktop Configuration Directory Structure

Source: https://github.com/ackness/covel/blob/main/docs/guide/desktop-config.md

Illustrates the default directory structure for the desktop application, including configuration files and data storage locations. The data root can be customized.

```tree
~/.covel/                    ← 配置根（小文件，随应用版本稳定）
  config.toml                ← 数据位置指针 + 日志轮转参数（见下文）
  llm.toml                   ← LLM slot 配置（provider / model / baseUrl）
  keys.env                   ← provider API key，KEY=VALUE 纯文本
  plugins/                   ← 用户插件（和 app bundle 内的核心插件合并）

<data_root>/                 ← 默认 ~/.covel/data；可改到任意路径
  covel.db                   ← SQLite 数据库
  worlds/                    ← 用户创建的世界
  logs/                      ← 应用日志（按尺寸轮转，NDJSON 一行一记录）
    desktop.log              ← Electron 主进程事件（窗口 / IPC / sidecar 监督 / 启动失败）
    server.log               ← Node sidecar 的 stdout/stderr（bootstrap 输出 + Hono 请求日志）
    desktop.log.1 … .N       ← 轮转副本，超过 max_files 丢弃最旧
    server.log.1 … .N
  server.port                ← 最近一次启动的端口（诊断用）
```

--------------------------------

### List Characters Tool

Source: https://github.com/ackness/covel/blob/main/plugins/char-creator/runtimes/character-tracker/PLUGIN.en.md

Call `list-characters` to get a compact list of all characters in the session. This is a mandatory first step before any character creation or update operations.

```tool_code
list-characters
```

--------------------------------

### Populate Token Reference List

Source: https://github.com/ackness/covel/blob/main/apps/web/public/design-system.html

Populates an HTML element with a list of design tokens and their descriptions. This is useful for creating a reference guide for available tokens.

```javascript
const tokenRef = [
  ["--type-display", "family · headline"],
  ["--type-body", "family · body"],
  ["--type-mono", "family · meta + IDs"],
  ["--surface-page", "global page background"],
  ["--surface-rail", "left/right vertical rails"],
  ["--surface-inset", "inputs, code blocks, debug rail"],
  ["--surface-elevated", "modal / popover only"],
  ["--rule-color", "every hairline divider"],
  ["--rule-strong-color", "section dividers, top of plates"],
  ["--rule-style", "solid · dashed · double"],
  ["--accent-primary", "main marker color"],
  ["--accent-secondary", "secondary state · info"],
  ["--accent-warning", "attention"],
  ["--accent-danger", "destructive · error"],
  ["--accent-success", "completion · live status"],
  ["--ambience-image", "theme-level background atmosphere"],
  ["--noise-opacity", "paper grain intensity"],
  ["--radius-card", "large radii (cards, dialogs)"
],
  ["--radius-control", "inputs, buttons, chips"],
  ["--radius-dialog", "modals"],
  ["--eyebrow-letter-spacing", "meta tracking"],
];
const list = document.getElementById("token-list");
list.innerHTML = tokenRef
  .map(
    (\[k, v\]) =>
      `<div class="token-entry"><span class="key">${k}</span><span class="val">${v}</span></div>`
  )
  .join("");
```