fuli-context 0.4.0 → 0.7.2

package/README.md

@@ -1,246 +1,484 @@
-# 复利（Fuli）
+<p align="center">
+  <img src="https://raw.githubusercontent.com/JevonsCode/fuli/main/web/assets/brand/fuli-logo.png" alt="Fuli logo" width="72" />
+</p>
 
-复利是一个面向 AI Agent 的本地优先上下文图谱。它让 Codex、Claude Code 和
-Cursor 在会话之间复用个人偏好、项目约束、历史决策与 Runbook，同时保留来源和
-知识边界。
+<h1 align="center">Fuli</h1>
 
-当前 npm 版本是个人版：个人知识与管理界面运行在本机。团队共享 Provider 是独立的
-服务部署单元，不作为第二个用户 npm 包发布。
+<p align="center">
+  English · <a href="README.zh-CN.md">简体中文</a>
+</p>
 
-## 安装
+<p align="center">
+  <a href="https://www.npmjs.com/package/fuli-context"><img src="https://img.shields.io/npm/v/fuli-context?style=flat&logo=npm&label=fuli-context" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/fuli-context"><img src="https://img.shields.io/npm/dm/fuli-context?style=flat" alt="npm downloads" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/fuli-context?style=flat" alt="license" /></a>
+</p>
 
-准备：
+Fuli is a local-first collaboration context graph for AI agents. It turns reusable knowledge,
+experience, decision rationale, and preferences from human–AI project work into assets with
+provenance, scope, authority, and temporal history. Codex, Claude Code, and Cursor can then reuse
+those assets in later tasks instead of relearning the same context.
 
-- Node.js 24.12 或更高版本
-- Docker Compose v2；Docker Desktop 或 Rancher Desktop 均可
-- 至少约 4 GB 可供容器使用的内存
+Fuli is not a transcript archive, and it is not an attempt to build a personality model that
+replaces human judgment. AI retrieves, summarizes, warns, and executes; humans retain final
+authority.
 
-全局安装并初始化：
+## npm packages
 
-```bash
-npm install --global fuli-context
-fuli setup
-```
+| Package | Status | Intended use |
+| --- | --- | --- |
+| [`fuli-context`](https://www.npmjs.com/package/fuli-context) | Available | Personal edition; personal knowledge, the graph database, and the management UI all run locally |
+| Fuli Server npm package | In development | A separate server for team-shared deployments; not yet published |
 
-`fuli setup` 会先展示即将进行的操作，再请求确认。它会检查容器运行时、初始化本机
-Graphiti / Neo4j、创建个人空间、安装配套 Agent Skills，并为检测到的 Agent 注册
-`fuli` MCP。Codex 接入还会在用户级 `AGENTS.md` 中合并一段很短的 Bootstrap：每个
-用户任务开始时先调用协作偏好工具，并把当前工作目录作为 `projectPath` 传给 Fuli。
-偏好正文仍以 Fuli 为唯一来源，不会复制到 Codex 配置中。默认不会连接或模拟团队共享
-Provider。
+`fuli-context` is currently the only available npm package. The shared layer never contains
+personal taste, personality, or judgment preferences.
 
-初始化完成后：
+## Philosophy
 
-```bash
-fuli open
-```
+### 1. Measure reuse value, not knowledge volume
 
-管理界面默认位于 `http://127.0.0.1:2727`。
+Fuli is built around one question:
 
-## CLI 使用
+> Without Fuli, would the agent have to relearn information that is confirmed, still valid, and
+> relevant to the current task?
 
-全局安装会提供两个等价命令：
+Node count, transcript count, and graph size are not success metrics. The product succeeds when a
+past collaboration asset is reused within the correct project, time, provenance, and authority
+boundaries—and reduces repeated explanation, correction, or rework.
 
-- `fuli`：完整命令名，文档默认使用它；
-- `fl`：短别名，例如 `fl status` 与 `fuli status` 完全相同。
+### 2. Review every task; do not retain every task
 
-查看版本和内置帮助：
+A task may produce:
 
-```bash
-fuli --version
-fuli --help
-```
+- reusable knowledge such as API conventions, runbooks, release procedures, or constraints;
+- experience explaining why an approach worked or failed;
+- a decision trace with options, a human choice, rationale, and later validation;
+- judgment aids such as preferences, principles, taste, or personality tendencies.
 
-### 本地服务与安装
+It may also produce only disposable output, a guess, or a one-off choice. In that case,
+`retain_nothing` is the correct result. Every task should perform a knowledge-value checkpoint, but
+not every task must become stored knowledge.
 
-| 命令 | 用途 |
-| --- | --- |
-| `fuli setup [选项]` | 初始化 Provider、管理界面、Agent 接入和 Skills；可重复执行 |
-| `fuli start [选项]` | 启动本机服务 |
-| `fuli stop [--data-dir DIR]` | 安全停止本机服务并保留数据 |
-| `fuli restart [选项]` | 重启本机服务 |
-| `fuli status [--json]` | 查看服务状态；`--json` 输出机器可读结果 |
-| `fuli open` | 在浏览器中打开管理界面 |
-| `fuli update [setup 选项]` | 更新全局 npm 包，并用新版 CLI 刷新本机接入 |
-| `fuli uninstall [--yes]` | 清理 Agent 接入和服务，保留知识数据 |
+### 3. Human authority outranks agent repetition
 
-常用示例：
+An agent may discover candidates, surface conflicts, recommend promotion, or resolve a deferred
+conflict when explicitly authorized. It may not turn semantic similarity, repetition, or its own
+judgment into human confirmation. Shared-knowledge promotion and sensitive project mutations use a
+preview followed by an explicit, one-time, atomic action.
 
-```bash
-fuli start
-fuli start --open
-fuli status
-fuli status --json
-fuli restart
-fuli restart --rebuild
-fuli stop
-```
+### 4. Assemble context, then retrieve evidence on demand
 
-`fuli stop` 只停止本机服务，不删除图谱数据。
+Fuli does not inject the complete history at session start. The entry step always loads effective
+personal-global preferences and preferences from one exactly matched project. When the current task
+signals that a stable prior fact, method, URL, decision, release, deployment, or authentication
+runbook may matter, the same step also performs a small bounded recall from that project and its
+authorized knowledge sources. The agent uses focused on-demand search when more evidence is needed.
+Retrieval alone is not usage; a usage event is recorded only when an item materially affects an
+answer, implementation, or decision.
 
-`start` 和 `restart` 可使用 `--data-dir DIR`、`--personal-space NAME`、`--port PORT`；
-`--open` 会在启动后打开管理界面，`--rebuild` 会重新构建本机 Provider 容器。
+### 5. Preserve evolution instead of overwriting history
 
-### setup 选项
+An old approach may have been correct under earlier conditions and later replaced. Fuli preserves
+provenance, confirmation authority, time, rationale, revisions, supersession, and negative evidence
+so an agent can explain both what applies now and why the past was different. Negative feedback may
+lower rank or trigger review, but it never silently erases history.
 
-| 选项 | 用途 |
-| --- | --- |
-| `--yes` | 跳过确认，适合无人值守执行 |
-| `--data-dir DIR` | 使用指定数据目录；后续命令应继续传入同一路径 |
-| `--personal-space NAME` | 设置首次初始化时的个人空间名称，默认是 `我` |
-| `--port PORT` | 设置管理界面端口，默认是 `2727` |
-| `--codex-only` | 只接入 Codex |
-| `--skip-agents` | 不修改 Agent 配置，也不刷新 Agent Skills |
-| `--no-start` | 初始化 Provider，但不启动管理界面 |
-| `--personal-only` | 只使用个人 Provider；这是默认模式 |
-| `--with-dev-public` | 同时启动本机开发用公共 Provider，仅用于开发或联调 |
-
-例如，无人值守地完成默认初始化：
+### 6. Put shared knowledge in the parent; keep differences in each child
 
-```bash
-fuli setup --yes
-```
+For example, hotel and flight projects can keep their own PRDs, configuration, and domain rules,
+while a parent activity-platform project owns shared local-run, mock, test, and deployment runbooks:
 
-使用自定义数据目录和管理界面端口：
+```text
+Activity platform (parent: shared runbooks)
+├── Hotel project (child: hotel PRD / configuration / overrides)
+└── Flight project (child: flight PRD / configuration / overrides)
+```
 
-```bash
-fuli setup --data-dir "./fuli-data" --port 3727
+When an agent works in the hotel project, it searches hotel-local knowledge first, then follows
+explicit outgoing `PART_OF` or `USES_KNOWLEDGE_FROM` relationships to authorized sources, up to two
+hops. A child item with the same stable key overrides an inherited item. Generic `RELATED_TO`
+relationships do not expand scope, and project-scoped personal preferences are not inherited.
+
+Similar items from multiple children create only a common-knowledge candidate. Current clustering
+is a lexical heuristic, not proof of semantic equivalence. A human must select the canonical item,
+duplicates, parent project, and rationale before an atomic promotion can occur.
+
+### 7. Local first; no personal model in the shared layer
+
+The personal graph stays local by default. Fuli stores structured reusable knowledge, not raw
+transcripts, credentials, temporary logs, or command output. The team-shared layer contains only
+confirmed project or domain knowledge with context and provenance—not personal taste, personality,
+or judgment preferences.
+
+## Agent interaction sequence
+
+This is the simplified lifecycle for a normal task. The Chinese
+[detailed sequence diagram](acceptance/智能体调用时序图.md) also covers inheritance, usage counting,
+write previews, and source markers.
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor U as User
+    participant A as Agent
+    participant L as Lifecycle integration
+    participant F as Fuli MCP
+    participant G as Local graph
+
+    U->>A: Submit a task in the current project
+    alt Claude Code (hook-enforced)
+        L->>F: begin_task_context(projectPath, taskPrompt)
+        F-->>A: Preferences, exact project, bounded recall, and task token
+    else Codex / Cursor (prompt fallback)
+        A->>F: get_collaboration_preferences(projectPath, taskPrompt)
+        F-->>A: Preferences, exact project, and bounded recall
+    end
+
+    A->>A: Inspect task_knowledge_recall
+    opt Historical context is needed and recall did not answer it
+        A->>F: search_current_project_knowledge with focused queries
+        F->>G: Search child first, then authorized parents
+        G-->>A: Bounded content, status, provenance, and history
+        opt Knowledge materially affects the result
+            A->>F: record_knowledge_usage
+        end
+    end
+
+    A->>A: Complete the implementation, validation, or answer
+    opt The task creates a decision, contradiction, or stale signal
+        A->>F: Record rationale or knowledge feedback
+    end
+    A->>F: checkpoint_task_knowledge
+    alt A small durable candidate batch exists
+        F->>G: capture_candidates
+    else Nothing should be retained
+        F-->>A: retain_nothing
+    end
+
+    alt Claude Code Stop hook
+        L->>F: verify_task_checkpoint
+        F-->>L: Allow stop only after review
+    else Prompt-fallback agent
+        Note over A,F: Same contract, but the host cannot deterministically block a missed review
+    end
+    A-->>U: Return the result and any Fuli sources actually used
 ```
 
-只初始化 Provider、不启动管理界面：
+## Read-only external knowledge
+
+One knowledge-base connection can be bound to one or more existing personal projects without
+granting Fuli write access to the source. Each target keeps independent retrieval mode, sync
+cursor, and error state. The Connections page supports multi-project assignment, connection
+checks, manual synchronization, disconnection, and a per-project conflict switch.
+
+| Connector | Read path | Current boundary |
+| --- | --- | --- |
+| MCP | Resources `list/read`; configured `search` / `fetch` tools | Default; HTTPS or loopback HTTP, plus stdio |
+| Notion | Page Markdown and Data Source queries | Current `2026-03-11` API; explicit page or data-source IDs |
+| Feishu / Lark | Wiki nodes, search, and Docx raw content | Docx text only; search may require a user access token |
+| RAG Retrieval API | Dify-compatible external-knowledge retrieval contract | Live only; for compatible endpoints or adapters in front of systems such as RAGFlow |
+| Trusted custom code | Local ESM `sync` / `retrieve` contract | Explicitly installed trusted code, not a sandbox |
+
+<a id="connect-external-knowledge"></a>
+
+### Connect one or more knowledge bases to a project
+
+One personal project can have multiple knowledge connections, and one connection can target
+multiple personal projects. Each submission adds a connection instead of replacing an existing
+one. Source configuration is stored once, while retrieval mode, synchronization state, and errors
+are isolated per target. Use Bind projects on an existing connection to add or remove targets.
+
+1. Create or confirm the target under Personal projects.
+2. If the source needs a token, set it in the environment that starts Fuli, then start or restart
+   the service. The binding stores only the environment-variable name. For example, run
+   `export PROJECT_KB_TOKEN='...'` and then `fl restart`.
+3. Open `http://127.0.0.1:2727/connections`. Under External knowledge, enter a connection name,
+   connector, one or more bound projects, and retrieval mode.
+4. For MCP HTTP, enter the server URL and optional token environment-variable name. For MCP stdio,
+   enter its command and arguments. For Notion, enter the token environment-variable name and Page
+   IDs or Data Source IDs. For Feishu/Lark, enter the token environment-variable name, region, and
+   an explicit Space ID, root-node token, or node tokens. For RAG Retrieval API, enter a
+   Dify-compatible endpoint, knowledge-base IDs, and an optional token environment-variable name.
+   A custom connector takes a trusted local ESM module and source JSON.
+5. Select Add connection and then Check. A successful `mirror` or `hybrid` binding can be synced;
+   a `live` binding reads its source when an Agent query runs.
+6. After creation, use Bind projects to add or remove projects and select a mode per project.
+
+The project graph shows an External knowledge source node and a Uses external knowledge edge for
+each assignment. This is a read-only projection of connection configuration. Live bodies are still
+retrieved only when an Agent invokes `search_connected_knowledge`; showing the node does not mirror
+content locally.
+
+Retrieval modes differ as follows:
+
+- `live`: read the third party at query time without storing a body mirror in Fuli; the source must
+  be available.
+- `mirror`: manually mirror read-only content into the bound personal project and query the graph.
+- `hybrid`: use both the local mirror and live source results; recommended when the connector
+  supports both capabilities.
+
+Bindings support `live`, `mirror`, and `hybrid` modes. Mirror content is written only to the bound
+personal project as `observed`, `pending`, `restricted`, local-only knowledge. Credentials are read
+from named environment variables and are not stored in binding JSON. Source writes are never part
+of the connector contract. Documents that look like credential material are skipped individually,
+reported by count, and never enter the graph or Agent context.
+
+<a id="external-knowledge-conflict-policy"></a>
+
+### Conflict policy
+
+The conflict policy is stored per personal project and applies across that project's personal
+graph, all external bindings, and explicitly selected public projects:
+
+- Ask in the Agent conversation is the default. The Agent presents conflicting content, source,
+  and scope separately so the user can choose.
+- Allow an Agent decision lets the Agent select the stronger or fresher source for the current
+  response and requires it to explain the basis. It never confirms, invalidates, overwrites, or
+  writes back any knowledge.
+
+From the project directory, an Agent can be asked: `Search the current project and connected knowledge bases for the payment callback contract; list conflicting sources and ask me to decide.`
+
+`search_connected_knowledge` keeps personal-graph evidence, each external binding, and explicitly
+selected public projects as separate source sets. Public-project aggregation is **Beta**. When an
+Agent finds a material conflict, the default policy is to show it in the conversation and ask the
+user; the optional Agent-decision policy applies to the current response only and cannot confirm,
+invalidate, or rewrite any source. Direct external-to-public binding, reviewed public promotion,
+scheduled sync, webhooks, and full deletion reconciliation remain **TODO**.
+
+See the [external-knowledge architecture and connector contract](docs/external-knowledge-architecture.md).
+
+## Current capabilities and evidence boundaries
+
+Core mechanisms covered by implementation and automated tests include:
+
+- a local personal space, exact project scope, and selective parent inheritance;
+- preference confirmation, deferred conflict resolution, revision history, and source markers;
+- bounded task-prompt recall, focused on-demand retrieval, and material-usage auditing;
+- task entry and completion checkpoints, plus Claude Code entry and Stop hooks;
+- decision options, rationale, and validation results supplied during initial capture;
+- knowledge-usage events, negative feedback, and content-generation isolation;
+- persistent scoped knowledge reviews with pause/resume watermarks;
+- common-knowledge discovery and preview-token-protected atomic promotion;
+- read-only multi-project MCP, Notion, Feishu/Lark, Dify-compatible RAG Retrieval API, and trusted-code bindings with connected retrieval.
+
+The following must not be presented as already proven:
+
+- the A/B thresholds in `FULI_ALIGNMENT_BENCHMARK.md` are acceptance conventions; claims that Fuli
+  reduces explanation or rework require a sufficiently large set of controlled, real paired tasks;
+- benchmark projects and conversations are explicitly labeled **MOCK / synthetic data**, not user or
+  production data;
+- the decision tool can include validation during initial capture, but it does not yet expose a
+  dedicated operation for appending immutable validation results to an existing `Decision`;
+- Claude Code has deterministic lifecycle hooks; Codex and Cursor currently use prompt fallback and
+  must not be described as equally enforced;
+- selected public projects in connected retrieval are Beta; external-to-public promotion and
+  background delta synchronization are not implemented.
+
+## Installation
+
+Requirements:
+
+- Node.js 24.12 or later;
+- Docker Compose v2 through Docker Desktop, Rancher Desktop, or another compatible runtime;
+- approximately 4 GB of memory available to the containers.
+
+Install globally and initialize:
 
 ```bash
-fuli setup --no-start
+npm install --global fuli-context
+fuli setup
 ```
 
-## 更新
+`fuli setup` first shows its plan and asks for confirmation. It then checks the container runtime,
+initializes local Graphiti / Neo4j, creates a personal space, installs the companion Agent Skills,
+and registers the `fuli` MCP with detected agents. The default setup connects only the personal
+Provider; it does not simulate a team-shared service.
+
+Open the management UI after setup:
 
 ```bash
-fuli update
+fuli open
 ```
 
-`fuli update` 默认先展示更新计划并请求确认。需要无人值守执行时：
+The default URL is `http://127.0.0.1:2727`.
 
-```bash
-fuli update --yes
-```
+The Settings page manages all seven local Fuli ports, LAN access, automatic capture, Agent access,
+UI language, and the resource refresh interval. Run `fuli restart` after saving port or LAN changes;
+the refresh interval applies immediately. The same page polls real memory and disk usage for the
+management service, Providers, Neo4j, application files, and local data. Memory is sampled on every
+poll; disk usage is sampled at most once per minute, with separate timestamps. Missing container metrics
+are shown as partial instead of being replaced with mock values. Browser-tab memory and shared
+container-VM overhead are excluded from the Fuli total.
 
-更新流程会先查询 npm 的 `latest` 版本；确认不会降级后，才安全停止旧版服务、安装当时
-的 `fuli-context@latest` 对应版本，再直接使用新安装版本的 CLI 执行 `setup --yes`。
-既有知识数据、配置备份和 Neo4j 数据卷不会删除；即使 npm 上已经是当前版本，也会刷新
-Agent 接入和配套 Skills。`update` 支持上表中的全部 setup 选项；使用过自定义数据目录、
-端口或 Provider 模式时，应在更新时重复传入相同选项。
+## CLI
 
-如果当前 CLI 来自尚未发布的工作区版本，并且版本号高于 npm `latest`，更新会在停止服务
-和安装包之前退出，避免把开发版本降级。
+The global package provides two equivalent commands: `fuli` and the short alias `fl`.
+CLI help, prompts, status output, and errors are always in English and do not follow the web or
+system locale. User data such as paths and space names is displayed unchanged.
 
-如果当前已安装版本尚不识别 `update`，需要先手动升级一次到包含该命令的版本：
+| Command | Purpose |
+| --- | --- |
+| `fuli --help` / `fuli -h` | List every public command and its available options |
+| `fuli --version` / `fuli -v` | Print the installed Fuli CLI version |
+| `fuli setup [options]` | Initialize the Provider, UI, agent integrations, and Skills; safe to rerun |
+| `fuli start [options]` | Start the Provider and UI, optionally opening a browser, rebuilding containers, or enabling LAN access |
+| `fuli stop [--data-dir DIR]` | Stop services without deleting data |
+| `fuli restart [options]` | Restart local services using the same runtime options as `start` |
+| `fuli status [--json] [--data-dir DIR] [--port PORT]` | Show UI, personal graph, and shared-service status; `--json` emits machine-readable output |
+| `fuli open [--data-dir DIR]` | Open the current management UI in the default browser |
+| `fuli update [setup options]` | Update the npm package and refresh local integrations |
+| `fuli uninstall [--yes] [--data-dir DIR]` | Remove agent integrations and services while preserving knowledge data and Neo4j volumes |
+
+Common commands:
 
 ```bash
-npm install --global fuli-context@latest
-fuli setup --yes
+fuli --version
+fuli status
+fuli restart --rebuild
+fuli start --lan
+fuli stop
 ```
 
-如果自动更新在 npm 安装或新版 setup 阶段失败，知识数据仍会保留。检查命令输出后可用
-上面两条命令恢复；使用过自定义 setup 选项时也要一并带上。
+`start` and `restart` accept `--data-dir DIR`, `--personal-space NAME`, `--port PORT`, `--open`,
+`--rebuild`, `--lan`, and `--no-lan`. When port or LAN flags are omitted, the saved Settings values
+are used. LAN mode listens on private IPv4 addresses and prints the reachable URLs, the
+`fuli` username, and a temporary access code generated for that start. The default remains
+loopback-only; internal Providers and Neo4j ports are never exposed by `--lan`. LAN mode uses
+HTTP Basic Auth and is intended only for trusted home or office Wi-Fi, not public deployment.
 
-## 卸载
+`setup` and `update` accept:
 
-先清理 Agent 接入，再移除全局 npm 包：
+| Option | Purpose |
+| --- | --- |
+| `--yes` | Skip confirmation for unattended setup |
+| `--codex-only` | Configure Codex only |
+| `--data-dir DIR` | Use a specific data and configuration directory |
+| `--personal-space NAME` | Set the personal-space name; defaults to `Personal` |
+| `--port PORT` | Set the management UI port; defaults to `2727` |
+| `--skip-agents` | Do not change agent configuration or Skills |
+| `--no-start` | Initialize the Provider without starting the UI |
+| `--personal-only` | Use only the personal Provider; this is the default |
+| `--with-dev-public` | Start a development shared Provider for local integration work only |
+
+Update:
 
 ```bash
-fuli uninstall
-npm uninstall --global fuli-context
+fuli update
 ```
 
-`fuli uninstall` 会：
-
-- 停止本机 Fuli 服务；
-- 从 Codex、Claude Code 和 Cursor 中移除 Fuli MCP 接入；
-- 只删除仍与当前安装包完全一致的 Fuli Skills，有本地修改的 Skill 会保留；
-- 保留个人图谱、配置备份与 Neo4j 数据卷。
-
-这样重新安装时可以继续使用原数据。数据永久删除不包含在自动卸载流程中，避免误删。
+The update flow verifies that it will not downgrade the installation, stops the old services,
+installs `fuli-context@latest`, and refreshes agent integrations. Existing knowledge, configuration
+backups, and Neo4j volumes remain intact. Reuse any custom setup options during updates.
 
-## 个人版边界
+Uninstall:
 
-- 个人知识写入本机 Provider。
-- Agent 归纳结构化知识，不保存整段会话。
-- Token、Cookie、私钥、凭据、临时日志与原始命令输出不会写入图谱。
-- Graphiti 的远程 LLM 路径被禁用；当前嵌入在本机计算。
-- 搜索按个人空间和项目范围显式限定，不会默认混入所有项目。
-- Fuli 不是实时监控或 Git 服务；实时错误和代码状态应从对应的监控、日志或 Git
-  工具获取。
-
-团队共享能力将通过单独部署的 Provider 提供。个人版 npm 继续作为本地 CLI、管理界面
-和 Agent 接入客户端，避免用户同时安装两个容易混淆的全局命令包。
-
-## Agent 工作方式
-
-Fuli 为支持的 Agent 安装两个用户级 Skills：
-
-- `capturing-session-knowledge`：按稳定知识边界检索和静默沉淀上下文；
-- `grilling-project`：帮助用户审视和补全个人项目资料。
+```bash
+fuli uninstall
+npm uninstall --global fuli-context
+```
 
-Codex 的用户级 Bootstrap 要求 Agent 在每个用户任务开始时、调用其他工具或回答之前，
-调用 `get_collaboration_preferences`。调用只把当前工作目录作为瞬时 `projectPath`
-传给本机 Fuli；绝对路径不会写入图谱，也不会出现在工具结果中。Fuli 在 MCP 服务端
-完成匹配：个人全局的品味、个性与判断偏好始终生效；只有仓库根、Codex worktree 的
-原仓库，或工作区内唯一的精确子项目对应一个已登记个人项目时，才叠加该项目偏好。
-模糊、多项目、待确认、已失效、冲突或其他项目的偏好不会进入实际生效列表。首次写入
-或更新 Bootstrap 后，新建或重新打开一个 Codex 任务，让用户级 `AGENTS.md` 重新加载；
-此后偏好修改会在下一次用户任务中重新读取，不需要重启 Codex。
+Automated uninstall does not permanently delete the personal graph, which allows a later install to
+reuse the same data.
 
-疑似冲突既可以立即人工处理，也可以标记为“交给 AI，使用时处理”。后者不会提前覆盖
-任何一条记录；只有后续任务确实需要相关偏好时，Agent 才会先比较双方并调用专用解决
-工具。解决结果会保留修订历史，并标明该偏好曾发生冲突、由 AI 处理及其判断依据。
-协作偏好页顶部的“已确认”“待确认”“疑似冲突”均为可点击入口；“待确认”会筛出对应
-记录并打开首条详情，可继续确认、纠正或标记失效。
+## Agent integrations and primary tools
 
-主要 MCP 工具包括：
+Fuli installs the `capturing-session-knowledge`, `grilling-project`, and `flreview` Skills for
+supported agents. `/flreview` offers all knowledge, personal preferences, or personal-project
+scope. If the user has no patience, it skips mood, time, and token questions and reviews only a
+small number of highest-priority items.
+Claude Code uses `UserPromptSubmit` and `Stop` hooks for the task lifecycle. Codex's user-level
+`AGENTS.md` and Cursor instructions use prompt fallback. Preference content remains in local Fuli as
+the single source of truth and is not copied into agent configuration.
 
-| 工具 | 用途 |
-| --- | --- |
-| `get_collaboration_preferences` | 获取当前会话实际生效的全局与项目级协作偏好 |
-| `resolve_deferred_preference_conflict` | 在相关任务首次使用前解决已交给 AI 的偏好冲突并留下审计标记 |
-| `capture_session_knowledge` | 批量写入个人知识或创建发布预审草稿 |
-| `search_knowledge_graph` | 在明确范围内查询个人偏好与项目知识 |
-| `get_knowledge_graph` | 获取有界节点—关系图 |
-| `list_knowledge_spaces` | 查看个人空间、项目与订阅 |
-| `upsert_personal_project` | 新建或更新个人项目资料 |
-| `revise_personal_knowledge` | 修正、失效或恢复个人知识 |
-| `get_graphiti_status` | 检查 Provider 与 Graphiti 状态 |
-
-## 本机服务
-
-| 服务 | 默认地址 |
+| Tool | Purpose |
 | --- | --- |
-| 个人 Neo4j Browser / Bolt | `127.0.0.1:7474` / `127.0.0.1:7687` |
-| 个人 Provider | `127.0.0.1:8787` |
-| Fuli 管理界面 | `127.0.0.1:2727` |
-
-如果端口被占用、Docker Compose 不可用或容器引擎未启动，setup 会在修改 Agent 配置前
-停止，并给出对应错误。
-
-## 源码开发
+| `begin_task_context` | Hook entry: resolve the task, run bounded recall when signaled, and create a task token |
+| `get_collaboration_preferences` | Fallback entry: read effective preferences and bounded task recall |
+| `search_current_project_knowledge` | Search the child first, then authorized knowledge sources |
+| `search_knowledge_graph` | Run a general query within an explicit bounded scope |
+| `search_connected_knowledge` | Search the graph, project-bound read-only sources, and selected public projects without merging provenance |
+| `record_knowledge_usage` | Record a citation or application that materially affected the result |
+| `record_knowledge_feedback` | Preserve rejection, failed validation, contradiction, or stale evidence |
+| `record_decision_trace` | Store options, rejected alternatives, rationale, and optional initial validation |
+| `capture_session_knowledge` | Store a small structured batch of durable candidates |
+| `checkpoint_task_knowledge` | Complete review with `capture_candidates` or `retain_nothing` |
+| `discover_common_knowledge_candidates` | Read-only discovery of possible parent-project knowledge |
+| `preview_common_knowledge_promotion` | Preview a human-confirmed promotion |
+| `apply_common_knowledge_promotion` | Apply the preview atomically with a one-time token |
+| `resolve_deferred_preference_conflict` | Resolve an AI-deferred conflict only when a task needs it |
+| `start_knowledge_review` | Start or resume an exact personal review scope |
+| `list_knowledge_review_candidates` | Rank candidates by time, conflicts, weight, and cross-session repetition |
+| `record_knowledge_review_progress` | Save keep, update, invalidate, skip, or defer outcomes |
+| `finish_knowledge_review` | Pause, or complete and advance the next-review watermark |
+
+## Privacy and safety boundaries
+
+- Personal knowledge is written to the local Provider.
+- Agents distill structured knowledge instead of storing raw transcripts.
+- Tokens, cookies, private keys, credentials, private contact details, temporary logs, and raw command
+  output must not enter the graph.
+- Graphiti's remote-LLM path is disabled; embeddings are currently computed locally.
+- Searches are bounded by personal space and project scope instead of mixing every project.
+- External connectors never write to third-party sources; raw credentials are rejected from stored
+  binding configuration.
+- Shared promotion requires auditable human confirmation. Agent usage evidence can promote an item
+  only as far as `agent_confirmed`.
+- Fuli is not a real-time monitoring or Git service; current state must be read from the relevant
+  source system.
+
+## Local services
+
+| Service | Default loopback address | Availability |
+| --- | --- | --- |
+| Fuli management UI | `127.0.0.1:2727` | Always |
+| Personal Provider | `127.0.0.1:8787` | Always |
+| Personal Neo4j Browser / Bolt | `127.0.0.1:8060` / `127.0.0.1:7687` | Always |
+| Development shared Provider | `127.0.0.1:8788` | `--with-dev-public` only |
+| Development shared Neo4j Browser / Bolt | `127.0.0.1:7475` / `127.0.0.1:7688` | `--with-dev-public` only |
+
+These seven ports can be changed in Settings. Provider and Neo4j bindings remain loopback-only even
+when the management UI is started in LAN mode.
+
+To access the UI from another device on the same Wi-Fi, run `fuli start --lan`. Starting LAN mode
+from a loopback-only runtime safely restarts only the management UI and preserves Provider and
+graph data. Disable LAN in Settings and run `fuli restart`, or run `fuli restart --no-lan`, to return
+to loopback-only mode. Starting LAN mode again rotates the temporary access code.
+
+If a port is occupied, Docker Compose is unavailable, or the container runtime is not running,
+setup stops before modifying agent configuration and reports the cause.
+
+## Acceptance and development
+
+- [Alignment Benchmark](FULI_ALIGNMENT_BENCHMARK.md)
+- [Chinese acceptance index](acceptance/README.md)
+- [Knowledge retrieval and confirmation diagrams](acceptance/知识检索与确认流程图.md)
+- [Read-only external-knowledge architecture](docs/external-knowledge-architecture.md)
 
 ```bash
 npm install
 npm test
 npm run test:package
+npm run test:external-knowledge:live
 ```
 
-Provider 验证：
+The external-knowledge live test temporarily downloads two public official documentation
+repositories, validates read-only synchronization and retrieval, then removes the complete
+temporary directory. It is network-dependent and is not part of the default test suite.
+
+Provider validation:
 
 ```bash
-python3 -m compileall -q graph-provider/fuli_graph
-python3 -m pytest -q graph-provider/tests
+python3.12 -m venv .venv
+. .venv/bin/activate
+python -m pip install "./graph-provider[dev]"
+python -m compileall -q graph-provider/fuli_graph
+python -m pytest -q graph-provider/tests
 docker compose -f compose.graphiti.yml config --quiet
 ```
 
-`npm run test:package` 会构建前端、生成真实 npm tarball、安装到隔离的全局前缀，并验证
-`fuli` / `fl`、版本号、帮助信息和已发布 Web UI。测试源码、QA 截图与内部设计文档
-都不会进入 npm 包。
+`npm run test:package` builds the web UI, creates a real npm tarball, installs it into an isolated
+global prefix, and verifies `fuli` / `fl`, version output, help output, and the packaged UI. Tests,
+QA screenshots, and internal design documents are excluded from the npm package.
 
 ## License