uclone-x 0.2.2__tar.gz → 0.3.1__tar.gz

{uclone_x-0.2.2 → uclone_x-0.3.1}/.gitignore

@@ -100,5 +100,20 @@ evals/reports/*.json
 # `artifacts/images/...`, and the UI reads a session's tool output from
 # `.sandbox/tool_artifacts/<session>/`. Fifty such PNGs were staged by a `git add -A` before
 # a gate run, and the check that classifies every tracked file refused them.
-artifacts/
+# Anchored to the root, where that output lands. Unanchored, `artifacts/` also matched the
+# source directories that share the name (`src/uclone_x/artifacts/`,
+# `frontend/src/components/artifacts/`, #1554), and the public export's commit silently left
+# the frontend one's ten files out. Anchoring covers any later directory of that name too,
+# which per-directory negations did not; `oss.export` now refuses a commit that drops a file.
+/artifacts/
+# The story library (`stories/`, #1555) and the Files screen's archive (`.archive/`, #1554)
+# land beside it for the same reason, anchored for the same reason (#1578).
+/stories/
+/.archive/
 .sandbox/
+
+# A clone's skill proposals and what approving, turning down or revoking them keeps
+# (#1827). These are one installation's review state, not shipped skill packages.
+ucx-agent-skills/.pending/
+ucx-agent-skills/.versions/
+ucx-agent-skills/.rejected/

{uclone_x-0.2.2 → uclone_x-0.3.1}/CHANGELOG.md

@@ -13,6 +13,164 @@ names does.
 Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Each date is
 the date that version was published.
 
+## [0.3.1] - 2026-09-28
+
+### Added
+
+- Clones build a knowledge list as they talk. After each turn a clone keeps the lasting
+  facts it learned, each clone has one list across all of its conversations, and the
+  relevant facts are recalled at the start of a turn. A fact you told a clone to forget
+  stays forgotten when older conversation knowledge is imported.
+- A local clone can be linked to uClone2 from Settings › Connections › uClone2 and
+  unlinked there; the clone's page says when it is linked. `ucx link run` keeps the links
+  online without the dashboard.
+- Clones can propose new skills. A proposal waits in Settings until a person approves the
+  exact version shown, and a skill is offered only to clones that hold every tool it
+  needs.
+- Each conversation keeps a complete, append-only session log, including full tool
+  results, and the developer trace checks every model request against it.
+- Anthropic prompt caching: requests mark cache breakpoints, and cache reads and writes
+  are counted in token usage, for Gemini as well.
+- Context windows for the current Claude models (Fable 5, Opus 5, Opus 4.5–4.8,
+  Sonnet 4.5/4.6).
+
+### Changed
+
+- One-to-one conversations, from every interface, now run as one-seat rooms, so a clone
+  builds its context the same way in a chat and in a room. Conversations started from
+  another interface open read-only in the app, with one writer per room.
+- Context is no longer compacted between the steps of a single turn, and a result the
+  clone has already seen is referred back to rather than repeated.
+- The Artist uses its case skills in the turn and normalizes Danbooru tags.
+- `pydantic` 2.12 or later is required, and the `http` extra now includes
+  `websockets`.
+
+### Fixed
+
+- A persona edit applies completely or not at all; a failed edit fails the turn instead
+  of leaving the clone half changed, and edits reach clones already seated in a room.
+- A name another participant shares is no longer filed as a fact about you, and names
+  are compared after Unicode normalization.
+- Unreadable records are moved aside instead of overwritten; Settings and the CLI say
+  when that happened, and three set-aside copies are kept.
+- When the setup alone fills the model's window, the clone says so plainly.
+- Setting only `LLM_PROVIDER` picks that provider's default model.
+- Korean text: particles match the name before them, and the trace panel is translated.
+- The PyPI page shows the README screenshots and says that `pip install uclone-x`
+  alone installs the library without the `ucx` command.
+
+## [0.3.0] - 2026-09-27
+
+### Added
+
+- Novel co-writing with the Writer. Stories are saved in the workspace as an outline,
+  a codex (characters, places, items, threads) and a manuscript, and outlive the
+  conversation that started them. New tools `story_library`, `story_outline`,
+  `story_codex`, `story_manuscript`, `story_context` and `story_audit` belong to the
+  Writer. Only one conversation writes a story at a time; opening it from another gives a
+  read-only copy until you take it over. Scenes can carry a `story_time`, so a flashback
+  sees the story as it was then. `muse_spark` draws idea cards for a genre.
+- Codex changes the Writer proposes (a death, a lost item) wait for your decision, with
+  the quote that shows them. **View story** lists them under "Waiting for your decision"
+  with **Approve** and **Reject**; nothing changes until you choose.
+- A **Files** button in the header lists the files clones saved, across every
+  conversation, filtered by kind and by conversation. Files can be archived and restored;
+  "Delete for good" is offered only on archived files. A story opens in a new
+  conversation with its story view.
+- In a one-to-one chat, Clone can ask Writer, Artist, Scout, Pioneer or Guardian for help
+  through the new `a2a_call` tool, and Writer can ask Artist for illustrations. A clone
+  that is called cannot call a further one.
+- Google Gemini can draw pictures. The `image_engine` setting takes `auto` (the default),
+  `local` or `gemini`, and `image_model` picks the Gemini model (default
+  `gemini-2.5-flash-image`). On `auto`, Gemini draws only when no local engine or remote
+  GPU is ready and your chat already uses Gemini with a saved key; on `local`, no picture
+  request leaves your machines. Settings › Images (previously Tools) offers the same
+  choice and shows what is drawing pictures now. `ucx media status` lists Gemini too.
+- Clones can have their own pictures. Choose one from a clone's profile ("Upload
+  picture…", "Ask {name} to make one", "Reset to default"), or with **Use as avatar**
+  under a picture in the conversation, with Undo. Uploads must be PNG, JPEG or WebP and
+  10 MB or smaller. Clones can set their own with the `set_avatar` tool. Pictures show in
+  the rail, including the Group Chats list, and in the conversation.
+- Settings has a "Remote GPU Worker (SSH Auto-Tunnel)" section that connects to a
+  workstation over SSH and starts ComfyUI there. By default only image generation runs on
+  it; tick "Also run the LLM on this worker (Ollama)" to move the chat model too. The
+  previous LLM address comes back when you disconnect.
+- Settings › Usage limits how many tokens paid models may use, across every conversation
+  and clone, over 10 minutes, 5 hours and a week, with presets or your own numbers. Local
+  models are not counted. A banner appears at 80% of a limit. At a limit, the next paid
+  call is refused before anything is sent, and the message says when paid models can be
+  used again. `UCLONE_USAGE_LIMIT_10_MINUTES`, `UCLONE_USAGE_LIMIT_5_HOURS` and
+  `UCLONE_USAGE_LIMIT_WEEK` set the same limits.
+- A "Fast model" for quick background work, such as choosing who speaks next, separate
+  from the chat model. It follows the chat model unless you choose one, in Settings or with
+  `ucx llm use --fast <model>`.
+- For OpenAI, Anthropic and Gemini, Settings lists the models the provider offers for your
+  key, marks one "(recommended)", and has "Refresh list"; it works before you save, and
+  says in plain words when the list cannot load. You can still type any model name.
+- `ucx key set <provider>` and `ucx key remove <provider>`; `ucx key list` shows each
+  saved key masked and whether an environment variable overrides it.
+- One Language setting (System default, English, Korean). Settings, the rail, the
+  conversation, the composer, tool steps and the dock are translated; the Files screen and
+  the story view are English only for now. Clones still answer in the language you write in.
+- When a provider refuses a turn, you are told which provider and why (key rejected,
+  quota, outage, unreachable, model not available), with a suggested fix.
+- If `ucx-agent-skills` is missing from the project UClone-X was started from, the CLI
+  and Settings › Skills say so.
+- The package metadata links to the GitHub repository: homepage, source, issues and this
+  changelog.
+
+### Changed
+
+- **API keys are saved per provider** in the settings file, so saving or switching one
+  provider never drops another's key, and each key is sent only to its own provider. An
+  old single saved key is read as its provider's key and rewritten in the new layout the
+  next time settings are saved; a key with no known provider is sent nowhere until you save
+  it again. `ucx key setup` now saves to the settings file and no longer writes `.env`.
+  UClone-X does not read `.env` itself: if you relied on one, load it into your shell or run
+  `ucx key set <provider>`.
+- **Environment variables outrank Settings.** `LLM_PROVIDER`, `*_MODEL`, `*_BASE_URL` and
+  `*_API_KEY` set in your shell win over saved settings, and Settings, `ucx key` and
+  `ucx llm use` say which variable is in effect. `ucx start` no longer sets `LLM_PROVIDER`
+  or the model for you, so the ones chosen in Settings take effect; unset your own exports
+  to let Settings decide. With no model set anywhere, a request is refused with a plain
+  message instead of falling back to a built-in model.
+- The per-session token limit is gone by default; the Usage limits above replace it.
+- **Skills approved before this release must be approved again.** `ucx skill approve` now
+  records approvals in `~/.uclone/skills/approvals.json`, asks you to type yes in the
+  terminal, and refuses when there is no terminal, so a script or a clone cannot approve a
+  skill. A skill edited after approval is not loaded, and Settings › Skills says why each
+  skill is not in use.
+- A persona's `allowed_tools` is the range of tools it may use, not a list that is always
+  loaded. With a local Ollama model and an embedder, each message gets a base set of tools
+  plus up to three matching ones, and a new `search_tools` tool lets the model add others.
+  Other providers get every allowed tool.
+- The image prompt skills `media-prompt-danbooru`, `media-prompt-flux` and
+  `media-prompt-generic` are replaced by `media-character`, `media-architecture` and
+  `media-engineering`, which load the section for the active image model.
+- Removed HTTP routes: `POST /api/turn`, `GET` and `DELETE /api/session/history`,
+  `POST /api/session/history/truncate` and `GET /api/agents`. Every conversation runs as a
+  room; use the rooms API, and `GET /api/personas` for the list of clones. Saved history is
+  kept.
+- Approving codex changes and changing diagnostics consent work only from a browser window
+  UClone-X opened; any other window offers "Open a confirmed window".
+- The rail no longer shows which clones are active.
+
+### Fixed
+
+- Gemini models can use tools; before, nearly every built-in tool was refused.
+- Ollama's model list uses the address typed in Settings, and says when nothing answers
+  there. `localhost`, `127.0.0.1` and `[::1]` on one port count as the same server.
+- A dashboard started with its own storage folder uses the model and usage limits saved
+  there.
+- Clicking a clone in the rail no longer jumps to a group chat it is in, and only one clone
+  is selected at a time.
+- Typing in the message box no longer redraws the whole conversation on every keystroke.
+- Gemini pictures keep the format Gemini returned (JPEG or PNG), and image links in
+  replies open.
+- Shell commands a clone runs no longer wait for keyboard input, `file_edit` keeps a
+  file's line endings, a tool call with wrong arguments names each one, and a sandbox that
+  cannot start is reported in a plain sentence.
+
 ## [0.2.2] - 2026-09-24
 
 ### Added

{uclone_x-0.2.2 → uclone_x-0.3.1}/PKG-INFO

@@ -1,7 +1,12 @@
 Metadata-Version: 2.5
 Name: uclone-x
-Version: 0.2.2
-Summary: Next-Generation Event-Driven AI Agent Core & High-Performance Collaboration Framework
+Version: 0.3.1
+Summary: Local AI clones with memory, tools and group chat, on an event-driven agent runtime
+Project-URL: Homepage, https://github.com/UClone-AI/uclone-x
+Project-URL: Documentation, https://github.com/UClone-AI/uclone-x#readme
+Project-URL: Source, https://github.com/UClone-AI/uclone-x
+Project-URL: Issues, https://github.com/UClone-AI/uclone-x/issues
+Project-URL: Changelog, https://github.com/UClone-AI/uclone-x/blob/main/CHANGELOG.md
 Author-email: Kenny Lim <kennylim@uclone.net>
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -13,12 +18,13 @@ Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Requires-Python: >=3.11
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: pydantic-settings>=2.2.0
-Requires-Dist: pydantic>=2.7.0
+Requires-Dist: pydantic>=2.12
 Requires-Dist: pyyaml>=6.0.1
 Provides-Extra: all
 Requires-Dist: accelerate>=0.31.0; extra == 'all'
@@ -26,6 +32,7 @@ Requires-Dist: anthropic>=0.25.0; extra == 'all'
 Requires-Dist: diffusers>=0.31.0; extra == 'all'
 Requires-Dist: fastapi>=0.110.0; extra == 'all'
 Requires-Dist: google-genai>=0.1.0; extra == 'all'
+Requires-Dist: jsonschema>=4.18.0; extra == 'all'
 Requires-Dist: linkml-runtime>=1.6.0; extra == 'all'
 Requires-Dist: networkx>=3.3; extra == 'all'
 Requires-Dist: openai>=1.25.0; extra == 'all'
@@ -49,6 +56,7 @@ Requires-Dist: tree-sitter>=0.21.0; extra == 'all'
 Requires-Dist: typer>=0.12.0; extra == 'all'
 Requires-Dist: uv>=0.1.30; extra == 'all'
 Requires-Dist: uvicorn>=0.29.0; extra == 'all'
+Requires-Dist: websockets>=15.0; extra == 'all'
 Provides-Extra: cli
 Requires-Dist: rich>=13.7.0; extra == 'cli'
 Requires-Dist: typer>=0.12.0; extra == 'cli'
@@ -56,6 +64,7 @@ Provides-Extra: code-intel
 Requires-Dist: tree-sitter-language-pack>=1.20.0; extra == 'code-intel'
 Requires-Dist: tree-sitter>=0.21.0; extra == 'code-intel'
 Provides-Extra: dev
+Requires-Dist: jsonschema>=4.18.0; extra == 'dev'
 Requires-Dist: playwright>=1.44.0; extra == 'dev'
 Requires-Dist: pyright>=1.1.360; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
@@ -67,6 +76,7 @@ Requires-Dist: uv>=0.1.30; extra == 'dev'
 Provides-Extra: http
 Requires-Dist: fastapi>=0.110.0; extra == 'http'
 Requires-Dist: uvicorn>=0.29.0; extra == 'http'
+Requires-Dist: websockets>=15.0; extra == 'http'
 Provides-Extra: llm
 Requires-Dist: anthropic>=0.25.0; extra == 'llm'
 Requires-Dist: google-genai>=0.1.0; extra == 'llm'
@@ -91,18 +101,45 @@ Description-Content-Type: text/markdown
 
 # ⚡ UClone-X
 
-**Event-driven AI agent core and multi-agent collaboration framework**
+**AI clones that run on your own machine — chat with them one-to-one or in a group,
+and let them remember, read your files, search and draw.**
 
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Python](https://img.shields.io/badge/Python-3.11+-blue.svg)](https://www.python.org/)
-[![LLM Agnostic](https://img.shields.io/badge/LLM-Gemini_|_Claude_|_OpenAI_|_Local-orange.svg)](docs/llm-agnostic-interface.md)
+[![LLM Agnostic](https://img.shields.io/badge/LLM-Gemini_|_Claude_|_OpenAI_|_Local-orange.svg)](https://github.com/UClone-AI/uclone-x/blob/main/docs/llm-agnostic-interface.md)
 
 </div>
 
 ---
 
+UClone-X is a local AI workspace. You install it, open the dashboard in your
+browser, and talk to *clones* — agents with their own instructions, memory and
+tools. A local model through Ollama works with no account and no API key; a
+Gemini, Claude or OpenAI key works too.
+
+Underneath is an event-driven agent runtime you can also use on its own: see
+[For developers](#for-developers).
+
+## What it looks like
+
+Ask a clone a question. Here the default **clone** answers with a structured
+summary on a local model (`ollama:qwen3:8b`):
+
+![A clone answering "Find latest AI technology in september" with a structured list of AI trends](https://raw.githubusercontent.com/UClone-AI/uclone-x/main/docs/assets/screenshots/research-conversation.webp)
+
+Or ask the **artist** clone for a picture. The image appears in the conversation,
+with links to open it in the browser or in Docs:
+
+![The artist clone showing a generated image for "beautiful girl with beautiful background"](https://raw.githubusercontent.com/UClone-AI/uclone-x/main/docs/assets/screenshots/image-generation.webp)
+
+---
+
 ## Install
 
+> On PyPI? The `pip install uclone-x` line PyPI prints at the top of the page
+> installs the library only, without the `ucx` command. Use one of the installs
+> below; with pip, that is `pip install "uclone-x[cli,http]"`.
+
 On macOS or Linux, paste this into a terminal:
 
 ```bash
@@ -166,19 +203,128 @@ pip install "uclone-x[all]"
 
 Every extra resolves on Python 3.11, 3.12 and 3.13.
 
-### From a terminal
+### Models
+
+`ucx install` downloads the local language model and the image checkpoint and
+checks that each one actually works; it reports a partial setup as incomplete
+rather than as success. You can also do this later from the dashboard.
+
+As a rough guide to what fits, from the installer's own advice:
+
+| Memory | Local model | Image generation |
+| :--- | :--- | :--- |
+| under 8 GB | use a cloud model (API key) | no |
+| 8–16 GB | `qwen3:1.7b`, or a cloud model | no |
+| 16–24 GB | `qwen3:8b` | 512 px |
+| 24 GB and up | `qwen3:8b` | 768 px |
+
+## Connecting a model
+
+Pick **one** of these:
+
+* **Local, no key.** Install [Ollama](https://ollama.com). `ucx start` finds it
+  and offers a model that fits; models can also be added and removed from
+  Settings, or with `ucx llm pull` and `ucx llm rm`.
+* **In the dashboard.** Open Settings, choose Gemini, Anthropic, OpenAI, vLLM or
+  Ollama, and enter the key or server address there. It is remembered for the
+  next start, in `~/.uclone/sessions/settings.json` as plain text — treat that
+  file like the key itself.
+* **From the environment.** `ucx` reads provider settings from environment
+  variables, which take precedence over what Settings saved:
+
+  ```bash
+  export ANTHROPIC_API_KEY=...        # or GEMINI_API_KEY, OPENAI_API_KEY
+  ucx start
+  ```
+
+  `ucx` does **not** read a `.env` file by itself. The repository's
+  `.env.example` lists every variable it understands; if you keep yours in a
+  `.env`, load it into the shell first (`set -a; . ./.env; set +a`).
+
+`ucx llm status` shows which providers it can reach.
+
+## What you can do
+
+* **Clones.** Six ship built in — clone (the default), writer, artist,
+  guardian, pioneer and scout. Create your own, or edit one, from Settings; the
+  connected model can draft its instructions for you. Each clone is a YAML file
+  in your workspace.
+* **Conversations.** One-to-one chats and group chats with several clones,
+  listed most recent first, with pinning, rename and delete. Replies stream as
+  they are written, including each tool call; messages render Markdown and math.
+  Group conversations can also be driven from the terminal with `ucx room`.
+* **Memory.** Every clone can record, look up and retract facts, and remembers
+  them across conversations. The dock's Remembers tab lists what each clone
+  saved.
+* **Files and images.** Clones read files in your workspace and in folders you
+  mark read-only, write only inside the workspace, and generate images in-process
+  (or through ComfyUI when one is running). What each turn produced appears in
+  the dock beside the conversation.
+* **Tools from elsewhere.** Connect MCP servers from Settings — a remote one by
+  URL, a local one by command, or by pasting a vendor's `mcpServers` snippet.
+* **The terminal.** `ucx run` is the same agent as an interactive REPL, with
+  streaming, tool calls and slash commands; `ucx run --prompt "…"` answers once.
+* **Your editor.** `ucx acp serve` lets an editor that speaks the Agent Client
+  Protocol talk to a clone.
+
+`ucx --help` lists every command.
+
+## Where your data lives
+
+UClone-X has no server of its own and no account. Conversations and dashboard
+settings are kept under `~/.uclone/sessions/` (`UCLONE_SESSION_DIR` moves them),
+each clone's memory under `~/.uclone/agents/` (`UCLONE_AGENTS_DIR`), and clone
+definitions are YAML files in the workspace folder.
+
+What leaves the machine is what you connect it to: your messages go to the model
+provider you chose, a web search goes to the search service, and an MCP server
+you add receives what its tools are called with. With a local model and no
+remote tools, nothing leaves at all.
+
+## Something went wrong?
 
-`ucx run` is an interactive terminal REPL with streaming responses, tool calls
-and slash commands. It reads its model from the environment — an API key such as
-`OPENAI_API_KEY`, or a local Ollama:
+`ucx` keeps a record of what failed, on your machine, and only if you allow it:
 
 ```bash
-OLLAMA_FAST_BASE_URL=http://localhost:11434/v1 OLLAMA_FAST_MODEL=qwen3:8b ucx run
+ucx report --enable     # start recording failures locally
+ucx report              # show what has been recorded
+ucx report --open       # open a pre-filled bug report in your browser
 ```
 
-`ucx llm status` reports which models are reachable.
+**Nothing is uploaded on its own.** There is no telemetry server and no account
+to sign into. `ucx report` prints the exact text that would be sent; `--open`
+fills in a GitHub issue form that you still have to submit yourself. If you have
+the GitHub CLI, `ucx report --submit` files it through your own `gh` login.
+
+What gets recorded: the error type, the code path it failed on, your UClone-X,
+Python and OS versions, and the error message. Your prompts and the contents of
+your files are never included, and paths are reduced — code paths to the file
+name, home directories to `~`.
 
-## What UClone-X is
+Masking is pattern-based, like every credential scrubber: it recognises the
+shapes that occur in practice — `sk-…`, `ghp_…`, home directories on Linux,
+macOS and Windows — and cannot promise to catch a token shape or a path layout
+nobody has seen. That is why `ucx report` shows you the text before anything is
+sent, and why the text is the last word on what leaves your machine.
+
+Turn it off with `ucx report --disable` and delete what was recorded with
+`ucx report --clear`.
+
+Common first-run problems:
+
+* **"No active LLM provider connected."** No model is reachable. Start Ollama
+  (`ollama serve`), or set a key in Settings or the environment — see
+  [Connecting a model](#connecting-a-model). `ucx llm status` says which
+  providers answered.
+* **A key in `.env` is ignored.** `ucx` reads the environment, not `.env`; load
+  the file into your shell first.
+* **`ucx: command not found` after the installer.** It is not on your PATH yet;
+  add the `export PATH=…` line the installer printed to `~/.zshrc` (or
+  `~/.bashrc`), or run it as `~/.local/bin/ucx` until then — see [Install](#install).
+
+## For developers
+
+### The runtime
 
 An agent runtime built around a non-blocking reactive event loop rather than a
 blocking request/response cycle. Agents yield when idle and wake on tool
@@ -199,7 +345,7 @@ external broker.
   reasons against instead of inventing structure per prompt.
 * **OpenTelemetry native** — traces, metrics and OTLP export built in.
 
-## Implementation status
+### Implementation status
 
 UClone-X is pre-1.0 and under active development. Read this section before
 depending on it.
@@ -209,60 +355,38 @@ depending on it.
 | Event bus, agent state machine, sessions | Implemented |
 | Tool runtime, MCP client, built-in tools | Implemented |
 | LLM connectors (Gemini, Claude, OpenAI, Ollama, vLLM) | Implemented |
+| Dashboard: conversations, clones, memory, settings | Implemented |
+| Local image generation | Implemented |
 | Sandbox isolation modes | Implemented (host and workspace); container and WASM partial |
 | Ontology engine, skills, code intelligence | Implemented, evolving |
-| Developer dashboard | Implemented |
 | A2A protocol | **Specified, not implemented.** No conformance is claimed |
 
-## Something went wrong?
-
-`ucx` keeps a record of what failed, on your machine, and only if you allow it:
-
-```bash
-ucx report --enable     # start recording failures locally
-ucx report              # show what has been recorded
-ucx report --open       # open a pre-filled bug report in your browser
-```
-
-**Nothing is uploaded on its own.** There is no telemetry server and no account
-to sign into. `ucx report` prints the exact text that would be sent; `--open`
-fills in a GitHub issue form that you still have to submit yourself. If you have
-the GitHub CLI, `ucx report --submit` files it through your own `gh` login.
-
-What gets recorded: the error type, the code path it failed on, your UClone-X,
-Python and OS versions, and the error message. Your prompts and the contents of
-your files are never included, and paths are reduced — code paths to the file
-name, home directories to `~`.
-
-Masking is pattern-based, like every credential scrubber: it recognises the
-shapes that occur in practice — `sk-…`, `ghp_…`, home directories on Linux,
-macOS and Windows — and cannot promise to catch a token shape or a path layout
-nobody has seen. That is why `ucx report` shows you the text before anything is
-sent, and why the text is the last word on what leaves your machine.
-
-Turn it off with `ucx report --disable` and delete what was recorded with
-`ucx report --clear`.
+### Documentation
 
-## Documentation
+The documents below are the design and specification of the runtime; they are
+written for contributors rather than as a user manual.
 
-* [Architecture overview](docs/architecture-overview.md)
-* [Event-driven agent core](docs/event-driven-agent-core.md)
-* [Core principles P0–P9](docs/principles/core-principles.md) — the normative
+* [Documentation index](https://github.com/UClone-AI/uclone-x/blob/main/docs/README.md)
+* [Module structure](https://github.com/UClone-AI/uclone-x/blob/main/docs/module-structure.md) — the packages as built, their layers
+  and dependency edges
+* [Architecture overview](https://github.com/UClone-AI/uclone-x/blob/main/docs/architecture-overview.md)
+* [Event-driven agent core](https://github.com/UClone-AI/uclone-x/blob/main/docs/event-driven-agent-core.md)
+* [Core principles P0–P9](https://github.com/UClone-AI/uclone-x/blob/main/docs/principles/core-principles.md) — the normative
   rules every part of the runtime is built against
-* [Product requirements](docs/PRD.md)
-* [CLI specification](docs/cli-specification.md)
-* [LLM-agnostic interface](docs/llm-agnostic-interface.md)
-* [Dynamic persona and sub-agent interface](docs/dynamic-persona-interface.md)
-* [Local collaboration engine](docs/local-collaboration-engine.md)
-* [Sandbox execution](docs/sandbox-execution-architecture.md)
-* [Ontology architecture](docs/agent-ontology-architecture.md)
-* [Skill system](docs/skill-system-architecture.md)
-* [Code intelligence (AST, LSP, SCIP)](docs/code-intelligence-lsp-scip.md)
-* [Telemetry](docs/telemetry-opentelemetry.md)
-* [A2A protocol specification](docs/a2a-protocol-spec.md)
-* [Security threat model](docs/security-threat-model.md)
-
-## Development
+* [Product requirements](https://github.com/UClone-AI/uclone-x/blob/main/docs/PRD.md)
+* [CLI specification](https://github.com/UClone-AI/uclone-x/blob/main/docs/cli-specification.md)
+* [LLM-agnostic interface](https://github.com/UClone-AI/uclone-x/blob/main/docs/llm-agnostic-interface.md)
+* [Dynamic persona and sub-agent interface](https://github.com/UClone-AI/uclone-x/blob/main/docs/dynamic-persona-interface.md)
+* [Local collaboration engine](https://github.com/UClone-AI/uclone-x/blob/main/docs/local-collaboration-engine.md)
+* [Sandbox execution](https://github.com/UClone-AI/uclone-x/blob/main/docs/sandbox-execution-architecture.md)
+* [Ontology architecture](https://github.com/UClone-AI/uclone-x/blob/main/docs/agent-ontology-architecture.md)
+* [Skill system](https://github.com/UClone-AI/uclone-x/blob/main/docs/skill-system-architecture.md)
+* [Code intelligence (AST, LSP, SCIP)](https://github.com/UClone-AI/uclone-x/blob/main/docs/code-intelligence-lsp-scip.md)
+* [Telemetry](https://github.com/UClone-AI/uclone-x/blob/main/docs/telemetry-opentelemetry.md)
+* [A2A protocol specification](https://github.com/UClone-AI/uclone-x/blob/main/docs/a2a-protocol-spec.md)
+* [Security threat model](https://github.com/UClone-AI/uclone-x/blob/main/docs/security-threat-model.md)
+
+### Working on UClone-X
 
 An installed build is for *using* the agent. To change it, work from a checkout:
 the development commands — `setup`, `test`, `dev` — exist only there, because
@@ -281,19 +405,19 @@ npm ci --prefix frontend   # the gate runs the frontend's vitest suite
 strict mode, the test suite at or above 70% branch coverage, and a passing
 frontend vitest suite. A change that does not pass it is not ready.
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for how patches reach this repository,
-and [docs/local-development-guide.md](docs/local-development-guide.md) for the
+See [CONTRIBUTING.md](https://github.com/UClone-AI/uclone-x/blob/main/CONTRIBUTING.md) for how patches reach this repository,
+and the [local development guide](https://github.com/UClone-AI/uclone-x/blob/main/docs/local-development-guide.md) for the
 longer setup walkthrough.
 
 ## About this repository
 
-This repository is the UClone-X runtime and its documentation. It is published
-from a private development repository, in periodic snapshots rather than as a
-mirror of that repository's history. The evaluation suites and multi-agent
-build tooling used to develop it are not part of the published subset; the
-runtime detects their absence and degrades cleanly, so `ucx eval` reports that
-no evaluation backend is installed rather than failing to start.
+This repository is the UClone-X runtime, its dashboard and its documentation. It
+is published from a private development repository, in periodic snapshots rather
+than as a mirror of that repository's history. The evaluation suites and
+multi-agent build tooling used to develop it are not part of the published
+subset; the runtime detects their absence and degrades cleanly, so `ucx eval`
+reports that no evaluation backend is installed rather than failing to start.
 
 ## License
 
-Apache 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE).
+Apache 2.0 — see [LICENSE](https://github.com/UClone-AI/uclone-x/blob/main/LICENSE) and [NOTICE](https://github.com/UClone-AI/uclone-x/blob/main/NOTICE).