fuli-context 0.5.0 → 0.7.2

package/README.md

@@ -1,198 +1,335 @@
-# 复利（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>
 
-[English](README.en.md)
+<h1 align="center">Fuli</h1>
 
-复利是一个面向 AI Agent 的本地优先协作上下文图谱。它把人与 AI 在项目中产生的、经得起
-复用的知识、经验、决策理由和偏好组织成有来源、有作用域、有时间关系的资产，让 Codex、
-Claude Code 和 Cursor 在后续任务中少重复学习一次。
+<p align="center">
+  English · <a href="README.zh-CN.md">简体中文</a>
+</p>
 
-复利不是聊天记录仓库，也不试图建立一个替代人的“人格模型”。AI 负责检索、提醒、归纳和
-执行；人始终保留最终判断权。
+<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>
 
-当前 npm 包是个人版：个人知识、图数据库和管理界面都运行在本机。团队共享 Provider 是
-独立部署的服务单元，不会把个人品味、个性或判断偏好发布到公共层。
+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.
 
-## 项目理念
+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.
 
-### 1. 衡量复用价值，而不是知识数量
+## npm packages
 
-复利的核心问题是：
+| 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，Agent 是否需要重新学习一条已经确认、仍然有效且与当前任务相关的信息？
+`fuli-context` is currently the only available npm package. The shared layer never contains
+personal taste, personality, or judgment preferences.
 
-节点数、对话数和图谱规模不是成功指标。真正需要验证的是：历史资产能否在正确的项目、时间
-和权威边界内被再次使用，并减少重复解释、修正和返工。
+## Philosophy
 
-### 2. 每个任务都检查价值，但不强迫每个任务沉淀
+### 1. Measure reuse value, not knowledge volume
 
-一次任务可能产生：
+Fuli is built around one question:
 
-- 可复用知识：API 约定、Runbook、发布方式或项目约束；
-- 经验：为什么某个做法有效或失败；
-- 决策轨迹：候选方案、人的选择、理由和后续验证；
-- 判断辅助：偏好、原则、品味或个性倾向。
+> Without Fuli, would the agent have to relearn information that is confirmed, still valid, and
+> relevant to the current task?
 
-也可能只有临时输出、猜测或一次性选择。此时正确结果是 `retain_nothing`。复利要求每个任务
-结束前做一次知识价值检查，并不是把每次聊天都变成长久记忆。
+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.
 
-### 3. 人的权威高于 Agent 的重复判断
+### 2. Review every task; do not retain every task
 
-AI 可以发现候选、指出冲突、建议公共化，也可以在得到授权后处理延迟冲突；它不能仅凭语义
-相似、重复出现或自己的判断伪造人工确认。公共知识提升和有风险的项目写入必须先预览，再由
-明确的人类选择触发一次性、原子执行。
+A task may produce:
 
-### 4. 先组装上下文，再按需取证
+- 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.
 
-Fuli 不会在会话开始时把全部历史塞给模型。入口阶段只加载当前任务实际生效的个人全局偏好
-和精确项目偏好；详细知识由 Agent 根据任务按需检索。只有真正影响回答、实现或决策的知识
-才记录为一次使用，单纯检索不会增加权重。
+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.
 
-### 5. 保留知识演化，而不是覆盖历史
+### 3. Human authority outranks agent repetition
 
-旧方案可能在当时正确，后来因条件变化被替代。Fuli 保存来源、确认权威、时间、理由、修订、
-替代和负面证据，让 Agent 能解释“现在应该用什么”以及“为什么过去曾经不同”。负面反馈会
-降低相关内容的排序或触发复核，但不会静默抹掉历史。
+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.
 
-### 6. 公共知识归属上级，项目差异留在子项目
+### 4. Assemble context, then retrieve evidence on demand
 
-例如，酒店和机票项目可以只保存自己的 PRD、配置和领域规则，把共同的本地运行、Mock、测试
-和发布方式收敛到活动平台项目：
+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.
+
+### 5. Preserve evolution instead of overwriting history
+
+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.
+
+### 6. Put shared knowledge in the parent; keep differences in each child
+
+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
-活动平台（父项目：共享 Runbook）
-├── 酒店项目（子项目：酒店 PRD / 配置 / 覆盖项）
-└── 机票项目（子项目：机票 PRD / 配置 / 覆盖项）
+Activity platform (parent: shared runbooks)
+├── Hotel project (child: hotel PRD / configuration / overrides)
+└── Flight project (child: flight PRD / configuration / overrides)
 ```
 
-Agent 在酒店项目工作时先搜索酒店本地知识，再沿显式的 `PART_OF` 或
-`USES_KNOWLEDGE_FROM` 关系向上搜索允许继承的知识，最多两跳。同稳定键的子项目内容覆盖
-父项目内容；普通 `RELATED_TO` 关系不会扩大作用域，项目级个人偏好也不会向下继承。
+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. 本地优先，公开层不包含个人模型
+### 7. Local first; no personal model in the shared layer
 
-个人图谱默认留在本机。Fuli 保存结构化、可复用的知识，不保存整段会话、凭据、临时日志或
-原始命令输出。团队共享层只承载经过确认、具有上下文和来源的项目或领域知识，不包含个人的
-品味、个性和判断偏好。
+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 交互时序
+## Agent interaction sequence
 
-下面是日常任务的简化时序。更完整的项目继承、使用计数、写入预览和来源标记流程见
-[智能体调用时序图](acceptance/智能体调用时序图.md)。
+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 用户
+    actor U as User
     participant A as Agent
-    participant L as 生命周期接入
+    participant L as Lifecycle integration
     participant F as Fuli MCP
-    participant G as 本地图谱
-
-    U->>A: 在当前项目提交任务
-    alt Claude Code（Hook 强制）
-        L->>F: UserPromptSubmit → begin_task_context
-        F-->>A: 生效偏好、项目和任务令牌
-    else Codex / Cursor（Prompt fallback）
-        A->>F: get_collaboration_preferences(projectPath)
-        F-->>A: 生效偏好和精确项目
+    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
 
-    opt 任务依赖历史知识
-        A->>F: search_current_project_knowledge
-        F->>G: 先查子项目，再查获授权的上级
-        G-->>A: 有界正文、状态、来源和历史
-        opt 知识实际影响结果
+    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: 完成实现、验证或回答
-    opt 产生决策、反证或失效证据
-        A->>F: 记录理由或知识反馈
+    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 有少量可复用候选
+    alt A small durable candidate batch exists
         F->>G: capture_candidates
-    else 没有值得长期保留的内容
+    else Nothing should be retained
         F-->>A: retain_nothing
     end
 
-    alt Claude Code Stop Hook
+    alt Claude Code Stop hook
         L->>F: verify_task_checkpoint
-        F-->>L: 已检查才允许结束
-    else Prompt fallback Agent
-        Note over A,F: 遵循同一契约，但宿主不能确定性阻止漏检
+        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: 返回结果与实际使用的 Fuli 来源
+    A-->>U: Return the result and any Fuli sources actually used
 ```
 
-## 当前能力与证据边界
-
-已经由实现和自动化测试覆盖的核心机制包括：
-
-- 本地个人空间、精确项目作用域和选择性上级继承；
-- 偏好确认、延迟冲突处理、修订历史和来源标记；
-- 任务入口、任务末尾知识检查，以及 Claude Code 的入口 / Stop Hook；
-- 决策选项、决策理由和首次记录时附带的验证结果；
-- 知识使用事件、负面反馈和内容代际隔离；
-- 公共知识候选发现，以及预览令牌保护的原子提升。
-
-仍需与“已经证明”区分的内容：
-
-- `FULI_ALIGNMENT_BENCHMARK.md` 中 A/B 阈值是验收约定；只有完成足量、同条件的真实配对任务
-  后，才能声称 Fuli 已降低重复解释或返工；
-- Benchmark 的测试项目和对话是明确标注的 **MOCK / 合成数据**，不是用户或生产数据；
-- 当前决策工具可在首次记录时附带验证，但还没有面向既有 `Decision` 单独追加不可变验证结果
-  的专用入口；
-- Claude Code 具备确定性的生命周期 Hook；Codex 和 Cursor 当前是 Prompt fallback，不能把两者
-  表述为同等强制能力。
-
-## 安装
-
-准备：
-
-- Node.js 24.12 或更高版本；
-- Docker Compose v2；Docker Desktop 或 Rancher Desktop 均可；
-- 至少约 4 GB 可供容器使用的内存。
-
-全局安装并初始化：
+## 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
 npm install --global fuli-context
 fuli setup
 ```
 
-`fuli setup` 会先展示操作计划并请求确认，然后检查容器运行时、初始化本机
-Graphiti / Neo4j、创建个人空间、安装配套 Agent Skills，并为检测到的 Agent 注册 `fuli`
-MCP。默认只连接个人 Provider，不会模拟团队共享服务。
+`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 open
 ```
 
-管理界面默认位于 `http://127.0.0.1:2727`。
+The default URL is `http://127.0.0.1:2727`.
+
+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.
 
 ## CLI
 
-全局安装提供两个等价命令：`fuli` 和短别名 `fl`。
+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.
 
-| 命令 | 用途 |
+| Command | Purpose |
 | --- | --- |
-| `fuli setup [选项]` | 初始化 Provider、管理界面、Agent 接入和 Skills；可重复执行 |
-| `fuli start [选项]` | 启动本机服务 |
-| `fuli stop [--data-dir DIR]` | 停止服务并保留数据 |
-| `fuli restart [选项]` | 重启本机服务 |
-| `fuli status [--json]` | 查看服务状态 |
-| `fuli open` | 打开管理界面 |
-| `fuli update [setup 选项]` | 更新 npm 包并刷新本机接入 |
-| `fuli uninstall [--yes]` | 清理 Agent 接入和服务，保留知识数据 |
-
-常用示例：
+| `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
 fuli --version
@@ -202,115 +339,146 @@ fuli start --lan
 fuli stop
 ```
 
-`start`、`restart` 和 `setup` 支持 `--data-dir DIR`、`--personal-space NAME`、
-`--port PORT` 等选项。`start` 和 `restart` 还支持显式的 `--lan`：管理界面会监听
-私有 IPv4 局域网地址，并在终端输出可访问地址、用户名 `fuli` 和本次启动生成的临时访问
-口令。默认启动仍只监听 `127.0.0.1`；内部 Provider、Neo4j Browser 和 Bolt 不会随
-`--lan` 开放。局域网模式使用 HTTP Basic Auth，只适合可信家庭或办公 Wi-Fi，不等同于
-HTTPS 公网部署。
+`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` 还支持：
+`setup` and `update` accept:
 
-| 选项 | 用途 |
+| Option | Purpose |
 | --- | --- |
-| `--yes` | 跳过确认，适合无人值守执行 |
-| `--codex-only` | 只接入 Codex |
-| `--skip-agents` | 不修改 Agent 配置或 Skills |
-| `--no-start` | 初始化 Provider，但不启动管理界面 |
-| `--personal-only` | 只使用个人 Provider；默认模式 |
-| `--with-dev-public` | 同时启动开发用公共 Provider，仅用于开发或联调 |
-
-更新：
+| `--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 update
 ```
 
-更新会先确认不会降级，再停止旧服务、安装 `fuli-context@latest` 并刷新 Agent 接入。
-既有知识、配置备份和 Neo4j 数据卷会保留。使用过自定义 setup 选项时，更新时应继续传入
-相同选项。
+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:
 
 ```bash
 fuli uninstall
 npm uninstall --global fuli-context
 ```
 
-自动卸载不会永久删除个人图谱，避免误删。重新安装后可以继续使用原数据。
+Automated uninstall does not permanently delete the personal graph, which allows a later install to
+reuse the same data.
 
-## Agent 接入与主要工具
+## Agent integrations and primary tools
 
-Fuli 为支持的 Agent 安装 `capturing-session-knowledge` 和 `grilling-project` Skills。Claude
-Code 使用 `UserPromptSubmit` 和 `Stop` Hook 接入任务生命周期；Codex 的用户级
-`AGENTS.md` 与 Cursor 指令使用 Prompt fallback。偏好正文始终以本机 Fuli 为唯一来源，
-不会复制到 Agent 配置中。
+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.
 
-| 工具 | 用途 |
+| Tool | Purpose |
 | --- | --- |
-| `begin_task_context` | Hook 入口：创建任务令牌并返回生效上下文 |
-| `get_collaboration_preferences` | Fallback 入口：读取全局与精确项目偏好 |
-| `search_current_project_knowledge` | 子项目优先、按授权关系向上检索 |
-| `search_knowledge_graph` | 在明确的有界范围内执行更通用的查询 |
-| `record_knowledge_usage` | 记录真正影响结果的引用或应用 |
-| `record_knowledge_feedback` | 保存拒绝、验证失败、冲突或过时证据 |
-| `record_decision_trace` | 保存选择、被拒方案、理由和可选初始验证 |
-| `capture_session_knowledge` | 批量写入少量、结构化的候选知识 |
-| `checkpoint_task_knowledge` | 以 `capture_candidates` 或 `retain_nothing` 结束知识检查 |
-| `discover_common_knowledge_candidates` | 只读发现可能属于上级项目的公共候选 |
-| `preview_common_knowledge_promotion` | 预览人类确认的公共知识提升 |
-| `apply_common_knowledge_promotion` | 使用一次性令牌原子执行提升 |
-| `resolve_deferred_preference_conflict` | 在实际需要时处理已授权给 AI 的冲突 |
-
-## 隐私与安全边界
-
-- 个人知识写入本机 Provider；
-- Agent 归纳结构化知识，不保存原始会话；
-- Token、Cookie、私钥、凭据、私人联系信息、临时日志和原始命令输出不得进入图谱；
-- Graphiti 远程 LLM 路径被禁用，当前嵌入在本机计算；
-- 搜索按个人空间和项目范围限定，不默认混入所有项目；
-- 公共提升需要可审计的人工确认，Agent 自己的使用证据最多晋级为
-  `agent_confirmed`；
-- Fuli 不是实时监控或 Git 服务，实时状态应从对应系统重新读取。
-
-## 本机服务
-
-| 服务 | 默认地址 |
-| --- | --- |
-| 个人 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` |
-
-需要同一 Wi-Fi 下的其他设备访问时，执行 `fuli start --lan`。若当前已经以本机模式运行，
-命令会安全重启管理界面并保持 Provider 与图谱数据不变。退出局域网模式可执行
-`fuli restart`；再次进入局域网模式会更换临时访问口令。
-
-如果端口被占用、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)
-- [中文验收索引](acceptance/README.md)
-- [知识检索与确认流程图](acceptance/知识检索与确认流程图.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