foxclaw 0.1.0 → 0.1.2

package/python/.github/workflows/release.yml

@@ -0,0 +1,183 @@
+name: Release
+
+# 两段式发布。为什么不能"打 tag 就自动上传":
+# PyPI / npm 的版本号**不可撤回** —— 传上去只能 yank(仍占号、仍能被 pin 装到),
+# 不能覆盖重发。所以 CI 的默认行为是「校验 + 构建 + 挂 GitHub Release」,
+# 真正的外发必须人工触发一次 workflow_dispatch,并在 environment 里审批。
+#
+# 阶段一(push tag v*):版本/tag 一致性 → 构建 wheel+sdist+npm tgz → 产物结构校验
+#                        → GitHub Release 附件(可反复重跑,错了删 tag 重来)
+# 阶段二(workflow_dispatch):勾 publish=pypi/npm/both + 填 ref=tag,审批后才上传
+#
+# 需要预先准备(仓库 Settings):
+#   Environments: pypi、npm(各配 Required reviewers → 这就是"审批门")
+#   Secrets:      PYPI_API_TOKEN(npt_... 项目级 token)、NPM_TOKEN(granular,仅 publish)
+# 换 OIDC 时:PyPI 用 pending publisher、npm 用 trusted publishing,
+# 把 publish-* 里的 password/NODE_AUTH_TOKEN 去掉并加 `permissions: id-token: write`。
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      publish:
+        description: "上传目标(需对应 environment 审批)"
+        type: choice
+        options: ["none", "pypi", "npm", "both"]
+        default: "none"
+      ref:
+        description: "要构建/发布的 tag(如 v0.1.0;发布时必填)"
+        type: string
+        default: ""
+
+permissions:
+  contents: read
+
+# 同一 tag 并发跑两次发布 = 两个进程抢同一个版本号
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.ref || github.ref }}
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install release toolchain
+        # 只装构建器,不 `pip install -e .`:构建 wheel 不需要 torch/faiss 那套运行时
+        # 依赖(唯一 import 的 release_check.py 是纯标准库),装了只会把 job 拖成 5 分钟。
+        run: |
+          python -m pip install --upgrade pip
+          pip install "build>=1.2"
+
+      # 发布必须锚定 tag:否则发出去的是分支 HEAD,版本号对不上任何 tag,
+      # 事后连"这版对应哪次提交"都答不上来。
+      - name: Require tag when publishing
+        if: github.event_name == 'workflow_dispatch' && inputs.publish != 'none'
+        env:
+          REF: ${{ inputs.ref }}
+        run: |
+          if [ -z "$REF" ]; then
+            echo "::error::publish=${{ inputs.publish }} 时必须填 ref(如 v0.1.0),不能发分支 HEAD"
+            exit 1
+          fi
+
+      - name: Version / tag gate
+        env:
+          TAG: ${{ github.event_name == 'push' && github.ref_name || inputs.ref }}
+        run: |
+          if [ -n "$TAG" ]; then
+            python tools/release_check.py --tag "$TAG"
+          else
+            python tools/release_check.py
+          fi
+
+      - name: Build wheel + sdist
+        run: python -m build --outdir dist
+
+      - name: Pack npm tarball
+        # 必须先跑 build.cjs:它把项目源码复制进 npm/python/,npm 包才算完整。
+        # `npm pack` 不触发 prepublishOnly(只有 publish 才触发),漏了这步打出来的
+        # 是 2KB 空壳——里面没有 python/,npx foxclaw 直接跑不起来。
+        # 同时 build.cjs 自带红线自检:含内部文档就 exit 1,构建随之失败。
+        working-directory: npm
+        run: |
+          node build.cjs
+          npm pack --pack-destination ../dist
+
+      - name: Artifact gate
+        # 包里出现 .env / docs/internal / 运行期数据 = 停下,不许发(宁可不出包)
+        run: python tools/release_check.py --dist dist --npm-tgz dist/*.tgz
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-dist
+          path: |
+            dist/*.whl
+            dist/*.tar.gz
+          if-no-files-found: error
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: npm-tgz
+          path: dist/*.tgz
+          if-no-files-found: error
+
+  github-release:
+    # 只有 tag 才挂 Release;手工触发构建不建 Release
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+
+      - name: Publish GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            gh release upload "$TAG" dist/* --clobber    # 重跑时覆盖附件,不重建 Release
+          else
+            gh release create "$TAG" dist/* --title "$TAG" --generate-notes
+          fi
+
+  publish-pypi:
+    if: >-
+      github.event_name == 'workflow_dispatch' &&
+      (inputs.publish == 'pypi' || inputs.publish == 'both')
+    needs: build
+    runs-on: ubuntu-latest
+    # environment 上配 Required reviewers:这一步停在"等待审批",人点了才动
+    environment: pypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-dist
+          path: dist
+
+      - name: Upload to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          packages-dir: dist/
+
+  publish-npm:
+    if: >-
+      github.event_name == 'workflow_dispatch' &&
+      (inputs.publish == 'npm' || inputs.publish == 'both')
+    needs: build
+    runs-on: ubuntu-latest
+    environment: npm
+    steps:
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: npm-tgz
+          path: dist
+
+      - name: Publish to npm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish ./dist/*.tgz --access public

package/python/Dockerfile

@@ -0,0 +1,64 @@
+# syntax=docker/dockerfile:1
+
+# Foxclaw — 认知智能体操作系统
+#
+# 一个镜像两种用法：
+#   1) 跑服务：docker run -p 8000:8000 foxclaw
+#   2) 跑全量回归（构建/CI 自检）：docker run --rm foxclaw python tests/run_all.py
+#
+# 镜像较大（>2GB）是 sentence-transformers/torch 的代价——语义检索与治理漂移检测
+# 都依赖真实 embedding，这是能力而非可裁剪项。测试锁 HF_HUB_OFFLINE 离线读预热缓存。
+
+FROM python:3.12-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    HF_HOME=/root/.cache/huggingface
+
+WORKDIR /app
+
+# 系统依赖：torch 需要 libgomp1（OpenMP 运行时）。slim 镜像默认缺失，
+# 缺了会在 import torch 时报 libgomp.so.1 找不到。
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends libgomp1 \
+    && rm -rf /var/lib/apt/lists/*
+
+# ── 依赖层（利用 Docker layer 缓存：改源码不重装 torch）──────────────
+# 必须拷 foxclaw/ 与 vendor/ 才能 editable install（HMR/HKC 是 vendor 内嵌、
+# 走 sys.path 加载，非 PyPI 依赖，见 pyproject.toml 注记）。
+COPY pyproject.toml ./
+COPY foxclaw/ foxclaw/
+COPY vendor/ vendor/
+
+# 依赖以 pyproject.toml 为唯一来源；dev extra 补 pytest/ruff/mypy/coverage +
+# openpyxl/python-docx（默认回归 test_file_ingest/test_domain_import 硬依赖），
+# 使镜像既能跑服务又能跑全量回归（与 CI 对齐）。
+# 【关键】先装 CPU 版 torch：PyPI 默认 torch 在 Linux 上会拖入整套 CUDA toolkit
+# （nvidia-* 十几个包 + cuda-toolkit，镜像 +4GB、下载极慢），而 Foxclaw 语义检索
+# 只需 CPU。先从 PyTorch 官方 CPU index 装好 torch，sentence-transformers 见
+# 约束已满足即不再重装 CUDA 版。
+# --mount=type=cache 复用 pip 下载缓存：改依赖后重建无需重下 torch 等大 wheel
+# --retries/--timeout：国内网络抖动时 pip 默认重试(5次/15s)偏短,会把 filelock 等
+# 依赖的 index 元数据请求超时误判为"无匹配发行版"(ResolutionImpossible),放宽后更稳。
+RUN --mount=type=cache,target=/root/.cache/pip pip install --upgrade pip \
+    && pip install --retries 8 --timeout 60 torch --index-url https://download.pytorch.org/whl/cpu \
+    && pip install --retries 8 --timeout 60 -e ".[dev]"
+
+# ── 预热默认 embedding（all-MiniLM-L6-v2）────────────────────────────
+# run_all.py 内部注入 HF_HUB_OFFLINE=1 离线读取。若镜像内没有缓存，
+# sentence-transformers 会降级为 n-gram 哈希嵌入——对中文几乎无区分度，
+# 语义漂移分恒为 1.0 → 治理测试全红（见 .github/workflows/ci.yml 的教训）。
+# 故在 build 期一次性下载好，运行期离线可用、不依赖外网。
+# 【HF_ENDPOINT】默认走 hf-mirror.com（国内直连 huggingface.co 常被墙、DNS 解析失败）；
+# 海外/CI 可 `docker build --build-arg HF_ENDPOINT= ...` 覆盖，或留空走官方 HuggingFace。
+ARG HF_ENDPOINT=https://hf-mirror.com
+RUN HF_ENDPOINT="${HF_ENDPOINT}" python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('all-MiniLM-L6-v2')"
+
+# ── 其余仓库内容（frontend 前端静态 / skills / docs 等）──────────────
+COPY . .
+
+EXPOSE 8000
+
+# 默认启动 API 服务；跑回归用：docker run --rm foxclaw python tests/run_all.py
+CMD ["python", "-m", "uvicorn", "foxclaw.api:app", "--host", "0.0.0.0", "--port", "8000"]

package/python/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 snowfoxHQ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/python/MANIFEST.in

@@ -0,0 +1,14 @@
+# sdist 必须自带 vendor/ 下的 HMR 与 HKC —— 它们是内嵌运行时,不是 PyPI 依赖。
+# 缺了它们,pip install 装出来的包记忆/知识子系统会整体降级为 None。
+graft vendor
+graft foxclaw
+
+# sdist 必须带正文文件:pyproject 的 readme 指向 README_CN.md,PyPI 项目页正文取自它。
+include README.md
+include README_CN.md
+include LICENSE
+
+prune vendor/__pycache__
+prune foxclaw/__pycache__
+global-exclude *.pyc
+global-exclude *.pyo

package/python/README.md

@@ -0,0 +1,192 @@
+# Foxclaw · A Personal Agent with Memory
+
+A **personal agent with memory** — to a user, an agent that remembers; to a developer, an agent runtime built on the HMR memory runtime: three collaborating agents, cross-layer Harness governance, with the memory/cognition layer fully decoupled from any LLM.
+
+```
+Traditional frameworks:  memory = storage,           agents = stateless execution
+Foxclaw:               memory = living cognitive runtime, agents = reason · learn · evolve
+```
+
+## What it is
+
+Foxclaw is not "yet another agent framework" but a personal agent that actually remembers; under the hood, an agent runtime. Its moats are independent of any LLM:
+
+- **ThoughtChain** — each agent's reasoning is an auditable, comparable directed graph, not a log
+- **Harness** — three-dimensional drift detection (semantic / tool / scope) + shadow-mode self-calibration + policy self-learning
+- **Evolution** — every harness truncation teaches the policy; the system gets sharper with use
+- **Runtime governance** — idempotency, crash recovery, loop detection, etc., keeping the system reliable under real-world operation
+
+Three agents: Supervisor (coordination), Finance, Office (learning + itinerary). Each has isolated memory and policy evolution, mounts external ecosystems via the Skill layer, and connects to mainstream messaging platforms via the channel layer. The former Assistant and Admin responsibilities are now **instruction skills** (`skills/general-assistant`, `skills/schedule-itinerary`) mounted on demand, not separate agents.
+
+## Domain kernels
+
+Finance / Office each mount an isomorphic kernel (pure-algorithm layer + external tool interface + gatekeeper):
+
+- **Finance** — budget reasoning, MAD anomaly detection, cash-flow forecast; gatekeeper with four permissions, emits approval requests rather than moving money. **Advanced trio**: structured evidence chains (explainable risk), financial data graph (trace who caused an overspend), reconciliation (3-tier matching + suspicious-charge detection).
+- **Office** — SM-2 spaced repetition (mastery + forgetting risk) + knowledge graph (cluster discovery).
+- **Office · itinerary** — TSP routing, reachability ("won't make it") detection, time conflicts, geo-clustering; integrates Amap.
+
+## Messaging platforms
+
+Four mainstream platforms via a unified channel abstraction, **each adapter implemented to its own official spec** (not one mold):
+
+| Channel | Model | Credential |
+|---------|-------|-----------|
+| WeChat | iLink Bot API, long-poll + context_token | scan-login token |
+| Feishu | event-subscription webhook + signature + token refresh | App ID/Secret |
+| Telegram | Bot API getUpdates polling | bot token |
+| Discord | Gateway WebSocket + REST | bot token |
+
+Closed loop (`ChannelDispatcher`): receive → Supervisor → reply to origin, with per-channel session isolation and idempotent dedup. See [docs/CHANNELS.md](docs/CHANNELS.md).
+
+## Runtime governance
+
+Keeps the system reliable under message redelivery, crashes, long tasks, and loops. See [docs/GOVERNANCE.md](docs/GOVERNANCE.md): idempotency guard, crash/restart recovery (boot_id avoids pid reuse), tool-loop detection, context compaction, hook standardization, steering queue.
+
+## Quick start
+
+```bash
+pip install fastapi uvicorn "httpx<0.28" openai cryptography websockets pyyaml numpy scikit-learn rich pydantic
+python tests/run_all.py        # full regression (all green)
+export DEEPSEEK_API_KEY=sk-...  # or ANTHROPIC_API_KEY; unset → stub
+python -m uvicorn foxclaw.api:app --port 8000
+```
+
+See [docs/RUN.md](docs/RUN.md). Chinese docs: [README_CN.md](README_CN.md).
+
+> **Windows**: don't place the project under OneDrive-managed folders (Documents/Desktop/Pictures); Python can't create dirs inside redirect placeholders. Use a path like `C:\foxclaw`.
+
+## Knowledge base (HKC) model config
+
+HKC's knowledge base uses **two different types of models**, each for one job, both configured in `.env` — no code changes:
+
+| Stage | Model type | What it does | Config keys |
+|-------|-----------|-------------|-------------|
+| Write (ingesting books/files) | **Generative LLM** (reads & emits JSON) | Extracts entities / concepts / facts / claims from each chunk | `HKC_LLM_*` |
+| Retrieve (querying) | **embedding** (text → vector) | Vectorizes knowledge & queries, ranks by semantic similarity | `HKC_EMBEDDING_*` |
+
+They are not interchangeable: an embedding model cannot generate text (can't produce JSON), and an LLM is not suited to vector search.
+
+### First, pick your case
+
+| Your environment | Extraction model setup | `HKC_LLM_API_KEY` value |
+|---|---|---|
+| Have local Ollama | `openai-compatible` + `base_url` pointing at Ollama | **any non-empty value** (Ollama ignores it; `ollama` is just a placeholder) |
+| No local model | Use a **public cloud model** (DeepSeek / OpenAI / Qwen …), see table | the platform's **real API key** |
+
+### Case A · local Ollama
+
+```bash
+HKC_LLM_PROVIDER=openai-compatible
+HKC_LLM_API_KEY=ollama                       # placeholder only for local Ollama; never use this for cloud
+HKC_LLM_MODEL=my-qwen-32k:latest             # a model name from your `ollama list`
+HKC_LLM_BASE_URL=http://localhost:11434/v1   # Ollama's OpenAI-compatible endpoint
+HKC_LLM_TIMEOUT=180                          # local models are slow; relax the default 60s
+HKC_EXTRACT_CONCURRENCY=2                    # 1–2 for local, up to 5 for cloud APIs
+HKC_EXTRACT_BATCH=8                          # optional: extract N chunks per call, saves tokens & time; default 1 = per-chunk
+HKC_MAX_CHUNKS_PER_DOC=800                   # optional: per-doc chunk cap; default 800 (~1.25M chars); 0 = no cap, see below
+```
+
+### Case B · public cloud model (no local model)
+
+`HKC_LLM_MODEL` is the platform's **public model id** (passed through verbatim); `HKC_LLM_API_KEY` is the platform's **real key**:
+
+| Platform | `HKC_LLM_PROVIDER` | `HKC_LLM_API_KEY` | `HKC_LLM_MODEL` example | `HKC_LLM_BASE_URL` |
+|---|---|---|---|---|
+| DeepSeek | `deepseek` | `sk-...` (DeepSeek key) | `deepseek-chat` / `deepseek-reasoner` | leave blank (official default) |
+| OpenAI | `openai` | `sk-...` (OpenAI key) | `gpt-4o-mini` / `gpt-4o` | leave blank |
+| Qwen (Alibaba) | `openai-compatible` | DashScope key | `qwen-max` / `qwen-plus` | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
+| Zhipu / Moonshot / MiniMax … | `openai-compatible` | that platform's key | that platform's model id | that platform's OpenAI-compatible URL |
+
+DeepSeek example:
+
+```bash
+HKC_LLM_PROVIDER=deepseek
+HKC_LLM_API_KEY=sk-your-deepseek-key
+HKC_LLM_MODEL=deepseek-chat
+```
+
+### Retrieval model (embedding)
+
+The retrieval model does **not** use Ollama; it uses sentence-transformers, and auto-downloads weights from HuggingFace when missing locally:
+
+```bash
+HKC_EMBEDDING=local
+HKC_EMBEDDING_MODEL=BAAI/bge-m3          # auto-downloads on first use (~2.2 GB); or a local path like C:\...\bge-m3
+```
+
+Leave it unset if you don't need semantic precision (defaults to `stub` pseudo-semantics, works out of the box).
+
+### Where to put the key, and precedence
+
+- **`.env` is the source of truth** — read at startup; restart after editing.
+- The "extraction model" section in the planet page's connection settings is an **optional runtime override** (stored in browser localStorage, may override `.env` on refresh); leave it blank to always follow `.env`.
+- The page's first "API Key" field is the backend auth token (`.env`'s `FOXCLAW_API_KEY`), unrelated to the model keys.
+
+> Note: switching the embedding model changes the vector dimension (e.g. 384 → 1024), so you must rebuild the knowledge index (clear and re-ingest).
+
+### How much can I ingest at once?
+
+**The limits are hard — exceeding them returns an error, never a silent truncation:**
+
+| Entry point | Limit | On overflow |
+|---|---|---|
+| File upload (`/knowledge/ingest/file`, `/ingest/file/async`) | **20 MB per file** | `413 file too large` |
+| Pasted text (`/knowledge/ingest/text`) | **2,000,000 characters** | `413 text too large` |
+| Chunks per document | **800 by default** (~1.25M chars); `HKC_MAX_CHUNKS_PER_DOC=0` disables the cap | Only the first N chunks are processed, with a "document too large" warning |
+
+Supported formats: `.pdf` `.md` `.markdown` `.txt` `.epub` `.mobi` `.azw3` `.azw` `.docx` `.xlsx`. `.doc` is not supported, and **scanned PDFs get no OCR** — image-only pages yield no text at all.
+
+**A chunk is the billing and timing unit**, and it is fixed:
+
+```
+max 1792 chars per chunk, 224 chars of overlap
+→ roughly 1 chunk per 1568 characters
+```
+
+**Time and cost reference** (batch=4, concurrency=8, cloud DeepSeek, CJK content):
+
+| Content | File size | Chunks | Expected time |
+|---|---|---|---|
+| 100k chars | ~100 KB | ~64 | ~6 min |
+| 500k chars | ~500 KB | ~320 | ~32 min |
+| 1M chars | ~1 MB | ~640 | ~1 hour |
+| 7M chars (ceiling) | ~20 MB | ~4400 | ~7 hours |
+
+Token ratio: **~4k input + 2k output tokens per 10k characters** (batch extraction already amortizes the system prompt) — multiply by your provider's rates. English content is 2–3× the characters of CJK for the same bytes, so it costs proportionally more.
+
+**Practical guidance:**
+
+- **Keep single files at 2–5 MB.** That covers an ordinary ebook, finishes within tens of minutes, and lets you watch progress.
+- **Leave `HKC_MAX_CHUNKS_PER_DOC` at its default of 800.** Read the section below before lifting it — the reason is not just "it's slow".
+- **Use file upload, not paste, for anything long.** `/ingest/text` is synchronous and holds the request; `/ingest/file/async` runs in a background thread and exposes `processed/total` progress.
+- **Re-uploading the same file is free.** Content SHA-256 is checked first and duplicates return `409 already ingested`.
+- **When extraction fails, check the log keyword first.** "JSON parse failed" means the model's output was cut off mid-JSON (common with dense CJK documents) — lower `HKC_EXTRACT_BATCH` or raise `HKC_EXTRACT_MAX_TOKENS` (default 8192, the output ceiling). Only when that keyword is absent should you check the API key or network.
+
+### Per-document chunk cap: why the default is 800
+
+`HKC_MAX_CHUNKS_PER_DOC` defaults to **800 chunks**, chosen as the intersection of "covers real documents completely" and "finishes in a time you can sit through, at a cost you can predict":
+
+| Cap | Characters covered | Chunks | Expected time | Cost (cloud) |
+|---|---|---|---|---|
+| **800 (default)** | ~1.25M | 800 | ~1.3 hours | ~$0.4 |
+| 2000 | ~3.1M | 2000 | ~3.3 hours | ~$1 |
+| 0 (uncapped, i.e. a full 20 MB file) | ~7M | ~4400 | **7+ hours** | ~$2.3 |
+
+> Costs are rough order-of-magnitude estimates at DeepSeek list prices; scale for your provider.
+
+**Why not raise it (and especially not to 0):** uploads accept up to 20 MB. With no chunk cap, one accidental upload — a 20 MB scanned PDF, a rotated log dump — runs in the background for the better part of a day while billing the whole time. Ingestion runs on a background thread with no checkpoint and no rollback button: you either watch it finish or kill the whole service. The default exists to stop obviously unreasonable volumes up front, not to be as restrictive as possible.
+
+**Why not shrink it either:** past the cap only the first N chunks are processed, and the **whole file's SHA-256 is already recorded** as ingested. Re-uploading the same file is rejected with `409`. So a truncated ingest cannot be completed by "raising the cap and sending it again" — you must split the file by chapter and upload the parts separately. 800 chunks leaves enough headroom that ordinary documents and normal ebooks never hit the cap.
+
+**If you genuinely need a whole book,** raise the cap (or set 0) for that one ingest and set it back to 800 afterwards. A "document too large: split into N chunks" warning in the log means truncation happened, and it reports how much was dropped.
+
+## Philosophy
+
+Memory and cognition are fully decoupled from the LLM. The model is a replaceable text generator; the real moat (ThoughtChain audit + Harness drift + policy self-learning + domain kernels) exists independently of any model.
+
+## License
+
+MIT — see [LICENSE](LICENSE). Use it, modify it, ship it, sell it; just keep the copyright notice.
+
+The runtimes vendored under `vendor/` keep their own licenses (see `vendor/hkc/LICENSE`).