narraeon 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,164 @@
+# Narraeon
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+Narraeon is a local-first workspace for open-ended role-playing with an AI host. You build a world from readable YAML and Markdown files, connect the model provider you want to use, and then play through a browser connected to a Runtime on the same machine.
+
+The model handles the meaning of the story: it portrays characters, responds to the player's actions, reads world material when needed, and proposes durable changes. The Runtime handles the parts that should not depend on model memory: validated file operations, exact committed narrative, immutable history, recovery, and independent world forks.
+
+## What Narraeon provides
+
+- **File-native worlds.** Characters, locations, rules, the current situation, the opening, and world-specific instructions remain ordinary YAML and Markdown files.
+- **Durable continuity.** Important changes are written back to the document that naturally owns them. Exact player and host prose is committed as narrative history.
+- **Model-directed play.** The model can narrate, read additional material, and update world documents through Runtime tools in one continuous call chain.
+- **Inspectable prompts.** Prompt Preview shows the real logical roles, selected material, tool definitions, provider mapping, and cache boundary without calling the model.
+- **Non-destructive history.** Editing an earlier player action changes the current timeline without deleting old Authority records. Creating a fork produces a separate world that can evolve on its own.
+- **Local ownership.** Worlds, configuration, credentials, prompts, history, and recovery data are stored on your machine. Model requests go only to the provider endpoint you explicitly configure.
+
+## Requirements
+
+- Node.js **24.12.0 or newer**
+- A modern browser
+- For AI play or setting improvement, a model endpoint and API credential compatible with one of the supported adapters:
+  - OpenAI Responses API
+  - OpenAI-compatible Chat Completions
+  - Anthropic Messages
+
+Narraeon includes connection presets for several providers and also accepts a custom endpoint. A model with reliable tool-calling support is recommended.
+
+## Quick start
+
+Run the packaged web app without installing it globally:
+
+```bash
+npx narraeon web
+```
+
+Narraeon starts on <http://127.0.0.1:4317> and opens the default browser. Keep the terminal process running while you use the app; press `Ctrl+C` to stop it.
+
+Useful options:
+
+```bash
+npx narraeon web --port 4318
+npx narraeon web --no-open
+npx narraeon --help
+```
+
+The server listens only on `127.0.0.1`. If the chosen port already hosts a compatible Narraeon instance, the CLI reuses it. If another program owns the port, startup fails instead of attaching to an unknown service.
+
+## Run from source
+
+```bash
+git clone https://github.com/narraeon/narraeon.git
+cd narraeon
+npm ci
+npm run build
+npm start
+```
+
+Then open <http://127.0.0.1:4317>. To run the built CLI instead of the source server:
+
+```bash
+node dist/node/cli/main.js web
+```
+
+## First-time setup
+
+1. **Choose the interface language.** Use the language selector in the header. The choice is saved locally. It changes the interface and Runtime-owned default prompts, but it does not rewrite content or custom prompts you have already saved.
+2. **Configure a model connection.** Open **Model connection**, choose a provider profile or custom endpoint, enter the API key and model ID, and set the model's real context-window and maximum-output limits. Saving a connection also makes it the active connection.
+3. **Prepare a content package.** Create a blank package or import a ZIP. A content package is a world template, not a live save. Its main surfaces are:
+
+   ```text
+   opening.md                 first prose the player reads
+   world/                     initial characters, places, rules, and situation
+   control/frame.yaml         deterministic prompt-material arrangement
+   control/blocks/*.md        instructions unique to this world
+   control/player-views.yaml  persistent information shown beside the story
+   ```
+
+4. **Edit or improve the setting.** You can edit files directly, or ask the model to create a visible plan and an isolated candidate. AI changes are not applied until you review and accept the complete file diff.
+5. **Review the play preset.** The built-in preset is ready to use and follows the selected language. Presets hold reusable host guidance, narrative prompts, follow-up requests, and optional interface extensions.
+6. **Create a world.** A usable content package can be copied into a new independent world. Later edits to the source package do not alter worlds that already exist.
+
+## How play works
+
+Opening a world shows the committed story as the primary surface, with persistent player views beside it. Write what your character attempts, says, or decides, then choose how to send it:
+
+| Action                         | What it does                                                                                                                                                   | What it does not do                                                                 |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| **New context**                | Rebuilds model context from the world's current endpoint, current prompts, selected material, and recent narrative, then appends the new player text.          | It does not clear the world, visible story, or saved call-chain history.            |
+| **Append context**             | Continues the current model transcript and appends the new player text. With no existing context, it starts a new one automatically.                           | It does not recompile the world bootstrap while the current context remains active. |
+| **Append with an empty input** | After an interrupted request, resends the saved provider request unchanged. After a complete response, asks the model to continue from the current transcript. | It does not invent a hidden player instruction or commit an empty player message.   |
+
+The response streams into the page. The model may narrate immediately, read a precise document or history item, update a world document, create a document, or combine narration and tools. Tool calls only modify an uncommitted candidate; the Runtime validates and commits accepted results. A later provider failure does not erase earlier results that were already committed.
+
+### Continuity across contexts
+
+Narraeon does not depend on one indefinitely growing chat. A new context is compiled from the current world, while committed narrative and important document changes remain available as durable continuity. Short-lived scene details can remain in recent narrative; facts that would cause a contradiction if forgotten belong in the relevant character, location, item, rule, or current-situation document.
+
+The call-chain panel keeps the actual request history for inspection: player messages, model prose, Runtime tool calls and results, usage, failures, and only the reasoning content the provider really returned. Internal processing is not presented as story text.
+
+### Edit, correct, or fork
+
+| Action                              | Result                                                                                                                                                                                 |
+| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Edit a committed player message** | Stays in the current world. Narraeon appends a timeline revision from that message's logical parent and continues from the replacement text. Old Authority records remain recoverable. |
+| **Create a fork**                   | Copies the selected Authority prefix into a new independent world. The source world is unchanged, and both worlds can continue separately.                                             |
+| **Continuity correction**           | Applies an explicit out-of-story correction to current documents as a new commit without pretending the correction happened inside the narrative.                                      |
+
+## Content packages and setting improvement
+
+A content package is editable before play. You can keep several packages, copy them, export them as ZIP files, or import packages without overwriting an existing local identity.
+
+AI setting improvement operates only on a package candidate. In the plan-first path, the model reads the selected material and proposes a visible creation plan before writing. You can also explicitly skip the plan. In both cases, the result must pass file, reference, control, player-view, and real Prompt Preview checks before it can be applied as one atomic package update. Existing worlds are never changed by package improvement.
+
+For a detailed Chinese authoring guide, see [docs/content-package-setting-authoring.md](docs/content-package-setting-authoring.md).
+
+## Language behavior
+
+English is the default interface language. Switching to Simplified Chinese updates:
+
+- the web interface;
+- Runtime-owned default host and narrative prompts;
+- Runtime tool descriptions and tool-use contracts;
+- the scaffold used for newly created blank content packages.
+
+Existing content packages, worlds, imported presets, copied presets, and user-edited prompt files are not translated or rewritten automatically.
+
+## Local data and privacy
+
+Narraeon uses the operating system's standard per-user application directories. To isolate an instance or choose explicit locations, set these variables before startup:
+
+| Variable               | Purpose                                                    |
+| ---------------------- | ---------------------------------------------------------- |
+| `NARRAEON_DATA_ROOT`   | Content packages, worlds, Authority history, and artifacts |
+| `NARRAEON_CONFIG_ROOT` | Model connections, app preferences, and play presets       |
+| `NARRAEON_LOG_ROOT`    | Runtime logs and AI failure diagnostics                    |
+| `NARRAEON_PORT`        | Local web port, default `4317`                             |
+
+The browser talks only to the same-machine Runtime. Local-first does not mean that remote model inference is offline: prompts, selected world material, tool exchanges, and generated text are sent to the provider you configure. API keys are stored in the local configuration and are not returned to the browser after saving.
+
+When a provider, response-format, Runtime-tool, or candidate-check error occurs, Narraeon creates a JSONL incident under `NARRAEON_LOG_ROOT/ai-failures`. It preserves the raw provider exchange and later recovery attempts, including reasoning or thinking actually returned by the provider. It does not invent hidden reasoning or record API keys and request headers. The files can still contain private prompts, world content, tool arguments, and provider-returned reasoning, so treat the log directory as sensitive.
+
+## Development
+
+```bash
+npm ci
+npm run build
+npm run check
+npx playwright install chromium
+TMPDIR=/tmp npm run test
+TMPDIR=/tmp npm run test:package
+```
+
+`npm run test:package` creates a real npm tarball, installs it in a temporary directory outside the repository, and verifies the packaged CLI, health endpoint, home page, and repeated-start behavior.
+
+Project contracts and architecture:
+
+- [CONTEXT.md](CONTEXT.md) — domain vocabulary
+- [docs/product-foundation.md](docs/product-foundation.md) — current V1 product contract
+- [docs/adr/](docs/adr/) — architectural decisions
+
+## License
+
+Apache-2.0

package/README.zh-CN.md

@@ -0,0 +1,164 @@
+# Narraeon
+
+[简体中文](README.zh-CN.md) | [English](README.md)
+
+Narraeon 是一个用于开放式 AI 角色扮演的本地优先工作区。你用易读的 YAML 和 Markdown 文件搭好世界，连接自己想用的模型服务，再通过浏览器连接同一台机器上的 Runtime 开始玩。
+
+模型负责故事语义：扮演人物、回应玩家行动、按需读取世界材料，并提出需要持续保存的变化。Runtime 负责不应该交给模型记忆的部分：验证文件操作、保存精确的已提交叙事、维护不可改写的历史、故障恢复，以及创建彼此独立的世界分叉。
+
+## Narraeon 提供什么
+
+- **文件原生的世界。**人物、地点、规则、当前情境、开场白和世界专属指令都是普通 YAML／Markdown 文件。
+- **可持续的连续性。**重要变化会写回自然承载它的文档；玩家和主持的精确原文则作为叙事历史提交。
+- **模型主导的游玩。**同一条调用链里，模型可以叙事、读取额外材料，也可以通过 Runtime 工具更新世界文档。
+- **可检查的提示词。**Prompt Preview 直接展示真实的逻辑 role、选中材料、工具定义、Provider 映射和缓存边界，不会调用模型。
+- **不破坏旧历史。**修改早期玩家行动会调整当前时间线，但不删除旧 Authority 记录；“创建分叉”则会得到一个可以独立演化的新世界。
+- **数据归你所有。**世界、配置、凭据、提示词、历史和恢复数据都保存在本机。模型请求只会发往你明确配置的 Provider 端点。
+
+## 运行要求
+
+- Node.js **24.12.0 或更高版本**
+- 现代浏览器
+- 如果要进行 AI 游玩或设定完善，还需要与以下任一适配器兼容的模型端点和 API 凭据：
+  - OpenAI Responses API
+  - OpenAI 兼容的 Chat Completions
+  - Anthropic Messages
+
+Narraeon 内置了多家 Provider 的连接预设，也允许手动填写自定义端点。建议选择工具调用能力稳定的模型。
+
+## 快速启动
+
+无需全局安装，直接运行已发布的 Web 应用：
+
+```bash
+npx narraeon web
+```
+
+Narraeon 会在 <http://127.0.0.1:4317> 启动并打开默认浏览器。使用期间需要保持终端进程运行；按 `Ctrl+C` 停止服务。
+
+常用选项：
+
+```bash
+npx narraeon web --port 4318
+npx narraeon web --no-open
+npx narraeon --help
+```
+
+服务只监听 `127.0.0.1`。如果选定端口已经运行兼容的 Narraeon，CLI 会直接复用；如果端口被其他程序占用，启动会明确失败，不会连接未知服务。
+
+## 从源码运行
+
+```bash
+git clone https://github.com/narraeon/narraeon.git
+cd narraeon
+npm ci
+npm run build
+npm start
+```
+
+然后打开 <http://127.0.0.1:4317>。如果想通过已构建的 CLI 启动，而不是直接运行源码服务：
+
+```bash
+node dist/node/cli/main.js web
+```
+
+## 首次使用
+
+1. **选择界面语言。**在顶部切换语言，选择会保存在本机。它会改变界面和 Runtime 自带的默认提示词，但不会重写你已经保存的内容或自定义提示词。
+2. **配置模型连接。**打开“模型连接”，选择 Provider 预设或自定义端点，填写 API Key、模型 ID，以及模型真实的上下文窗口和最大输出限制。保存时会同时启用这份连接。
+3. **准备内容包。**新建一份空白内容包，或者导入 ZIP。内容包是世界模板，不是正在游玩的存档。它主要包含：
+
+   ```text
+   opening.md                 玩家首次看到的故事正文
+   world/                     初始人物、地点、规则和当前情境
+   control/frame.yaml         决定提示材料的确定性编排
+   control/blocks/*.md        只属于这个世界的指令
+   control/player-views.yaml  故事旁边常驻显示的信息
+   ```
+
+4. **手工编辑或让模型完善设定。**你可以直接编辑文件，也可以让模型先生成一份可见计划，再在隔离候选中创作。必须先审阅完整文件差异并明确接受，AI 修改才会生效。
+5. **检查玩法预设。**系统自带的默认预设可以直接使用，并会跟随当前语言。预设包含可复用的主持方法、叙事提示、后置请求和可选界面扩展。
+6. **创建世界。**可用的内容包可以复制成一个独立世界。之后继续修改源内容包，不会改动已经创建的世界。
+
+## 怎么玩
+
+打开世界后，已提交的故事是页面主体，玩家视图则在旁边常驻显示。写下你的角色准备做什么、说什么，或者作出什么决定，然后选择这次怎样发送：
+
+| 操作             | 会做什么                                                                                     | 不会做什么                                         |
+| ---------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| **全新上下文**   | 从世界当前端点、当前提示词、选定材料和近期叙事重建模型上下文，再追加新的玩家原文。           | 不会清空世界、页面上的故事或已保存的调用链历史。   |
+| **追加上下文**   | 继续当前模型 transcript，并追加新玩家原文。没有既有上下文时，会自动按全新上下文开始。        | 当前上下文仍然活跃时，不会重新编译世界 bootstrap。 |
+| **空输入时追加** | 上次请求中断时，原样重发已保存的 Provider 请求；上次响应完整时，从当前 transcript 继续生成。 | 不会偷偷补一条玩家指令，也不会提交空玩家消息。     |
+
+响应会实时流式显示在页面上。模型可以直接叙事、精确读取一份文档或历史、更新世界文档、创建文档，也可以组合叙事和工具调用。工具调用只会修改未提交候选；Runtime 验证后才会接受并提交结果。后续 Provider 请求失败，也不会撤销前面已经提交的结果。
+
+### 跨上下文保持连续
+
+Narraeon 不依赖一段无限增长的聊天。全新上下文会从当前世界重新编译，已提交叙事和重要文档变化仍然作为持久连续性保留。短期场景细节可以留在近期叙事里；一旦忘掉就会导致明显矛盾的事实，则应当写进相关人物、地点、物品、规则或当前情境文档。
+
+调用链面板保留真实请求轨迹供检查：玩家消息、模型正文、Runtime 工具及结果、usage、失败，以及 Provider 真实返回的 reasoning。内部处理过程不会被写成故事正文。
+
+### 修改、修正和分叉
+
+| 操作                     | 结果                                                                                                         |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------ |
+| **修改已提交的玩家消息** | 留在当前世界。Narraeon 从这条消息的逻辑父端点追加一笔时间线修订，再从修改稿继续。旧 Authority 记录仍可恢复。 |
+| **创建分叉**             | 把选中的 Authority 前缀复制成一个全新的独立世界。来源世界不变，两个世界之后可以分别继续。                    |
+| **连续性修正**           | 在故事之外明确修正当前文档，以新提交保存，不会假装这笔修正是剧情内发生的事。                                 |
+
+## 内容包与设定完善
+
+内容包在创建世界前可以自由编辑。你可以保留多份内容包、复制、导出 ZIP，或者导入新包，不会覆盖已有的本地身份。
+
+AI 设定完善只作用于内容包候选。在“先生成计划”的路径中，模型会先读取选定材料并给出可见的创作计划，然后才开始修改；你也可以明确跳过计划。两条路径都必须通过文件、引用、控制、玩家视图和真实 Prompt Preview 检查，才能作为一笔原子的内容包更新应用。已经创建的世界永远不会被内容包完善改动。
+
+更详细的创作方法见 [docs/content-package-setting-authoring.md](docs/content-package-setting-authoring.md)。
+
+## 语言行为
+
+默认界面语言为英文。切换到简体中文后，以下内容会同步改变：
+
+- Web 界面；
+- Runtime 自带的默认主持提示和叙事提示；
+- Runtime 工具说明和工具使用契约；
+- 新建空白内容包时使用的初始文件。
+
+已有内容包、世界、导入预设、复制预设和用户编辑过的提示文件不会被自动翻译或重写。
+
+## 本地数据与隐私
+
+Narraeon 默认使用当前操作系统的标准用户应用目录。如果要隔离一份独立实例，或者自行指定存放位置，可在启动前设置：
+
+| 环境变量               | 用途                               |
+| ---------------------- | ---------------------------------- |
+| `NARRAEON_DATA_ROOT`   | 内容包、世界、Authority 历史和产物 |
+| `NARRAEON_CONFIG_ROOT` | 模型连接、应用偏好和玩法预设       |
+| `NARRAEON_LOG_ROOT`    | Runtime 日志和 AI 失败诊断         |
+| `NARRAEON_PORT`        | 本地 Web 端口，默认为 `4317`       |
+
+浏览器只与同机 Runtime 通信。“本地优先”不等于远程模型推理也离线：提示词、选中的世界材料、工具交换和生成文本会发送到你配置的 Provider。API Key 保存在本地配置中，保存后不会再返回给浏览器。
+
+发生 Provider、响应格式、Runtime 工具或候选检查错误时，Narraeon 会在 `NARRAEON_LOG_ROOT/ai-failures` 下创建 JSONL 事故记录。它会保存原始 Provider 交换和后续恢复尝试，包括 Provider 真实返回的 reasoning／thinking。它不会伪造隐藏思考，也不会记录 API Key 和请求 header。不过日志仍可能包含私密提示词、世界内容、工具参数和 Provider 返回的思考，因此应当把该目录视为敏感数据。
+
+## 仓库开发
+
+```bash
+npm ci
+npm run build
+npm run check
+npx playwright install chromium
+TMPDIR=/tmp npm run test
+TMPDIR=/tmp npm run test:package
+```
+
+`npm run test:package` 会生成真实 npm tarball，在仓库外的临时目录安装，再检查发布版 CLI、健康端点、首页和重复启动行为。
+
+项目契约与架构文档：
+
+- [CONTEXT.md](CONTEXT.md) —— 领域词汇
+- [docs/product-foundation.md](docs/product-foundation.md) —— 当前 V1 产品契约
+- [docs/adr/](docs/adr/) —— 架构决策
+
+## License
+
+Apache-2.0