fredporter · fredporter · Aug 20, 2026 · Aug 20, 2026
diff --git a/README.md b/README.md
@@ -1,173 +1,94 @@
-# uCore — Unified Development OS
+# uCore
 
-[![Python](https://img.shields.io/badge/Python-3.12-blue)]()
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue)]()
-[![License](https://img.shields.io/badge/License-Apache%202.0-green)]()
-[![Tests](https://img.shields.io/badge/Tests-301%20passing-brightgreen)]()
+uCore is the local-first host application for the uDOS development ecosystem.
+It provides the Vue shell, governed backend APIs, extension discovery, runtime
+health, and the Developer surface used to work with repositories under
+`~/Code`.
 
-uCore is a **local-first, AI-powered development daemon** that unifies syntax, automation, and runtime management.
+**Pre-release:** the architecture is being dogfooded directly from `main`; it is
+not yet a public release or a compatibility target.
 
-**Port:** 8484 | **Stack:** Python 3.12 + aiohttp + SQLite + Vue 3 + TypeScript
+## Canonical ownership
 
-## Quick Start
+| Repository | Owns |
+| --- | --- |
+| `uCore` | Host shell, Developer UI, governed capabilities, settings and extension loading |
+| `uFlow` | Durable missions, tasks, workflows, approvals and execution evidence |
+| `uKnowledge` | Vault discovery, search, indexing and knowledge APIs |
+| `uCode` | GridCore, rendering packages, terminal/runtime and code primitives |
 
-### First Time on macOS (Fresh System)
+Domain projects and `udos-*` extensions remain independently owned. They may
+integrate through the extension contract; their domain logic does not move into
+uCore.
 
-```bash
-curl -fsSL https://raw.githubusercontent.com/uDosGo/uCore/main/scripts/bootstrap.sh | bash
-```
-
-This installs Homebrew, Python 3.12, Node.js 22, pnpm, clones uCore, and starts everything.
+## Development
 
-The installer also validates and syncs locked vendor modules for a consistent
-uDos experience (SnackMachine core, udos-agents, udos-budget, udos-identity).
-
-### Already Have Prerequisites
+Required baseline: macOS, Python 3.12, Node.js 22+, and pnpm 9+.
 
 ```bash
 git clone https://github.com/uDosGo/uCore.git
 cd uCore
 ./scripts/setup.sh
-```
-
-### Vendor Module Lock (Deterministic)
-
-```bash
-# Refresh lock metadata from vendor/sources.yaml and validate
-./scripts/vendor_sync.sh --refresh-lock --check
-
-# Install locked Python vendor modules
-source .venv/bin/activate
-./scripts/vendor_sync.sh --install-python --check
-```
 
-### Verify
+# backend: http://localhost:8484
+pnpm dev:backend
 
-```bash
-curl http://localhost:8484/api/health
-# Look for 🍿 in the macOS menu bar
-# Frontend: http://localhost:5175
+# frontend: http://localhost:5175
+pnpm dev
 ```
 
-### Uninstall
+Enable Dev Mode from the uCore interface, then open
+`http://localhost:5175/developer`. The Developer surface is deliberately small:
 
-```bash
-./scripts/install.sh --uninstall
-```
+- **Code** — repository and file browsing;
+- **Repository** — working-tree review, stage/unstage and commit;
+- **Editor** — guarded file editing with diff review.
 
-## Architecture
+It also shows the current branch, open pull request and recent GitHub Actions
+runs through the authenticated `gh` CLI. Remote mutations follow the explicit
+branch → checks → pull request → merge sequence.
 
-uCore is the **host platform core**. Optional capabilities — workflow,
-knowledge, and domain plugins — live in dedicated repos and plug in via
-a lightweight extension contract.
-
-```
-Codex (external development) → Git/GitHub → uCore (port 8484)
-uCore guided agents → Ollama/OpenRouter/OpenAI APIs
-  │
-  ├── Core shell (uCore host-only)
-  │   ├── Skills (15 built-in) — backup, sync, route, ask vault
-  │   ├── Secrets — AES-256-GCM encrypted store
-  │   ├── Chat — AI providers via OpenRouter/Ollama/Gemini
-  │   ├── Surfaces (10) — Dashboard, Assistant, Server, Developer,
-  │   │                    System, Workflow, SnackMachine, BrowserUI,
-  │   │                    Documentation, uCode
-  │   ├── Plates — Vault plates, surface templates (Cookiecutter)
-  │   ├── Hivemind — MCP orchestration, template verification, audit
-  │   ├── TOON Context Optimization — Token-optimized context encoding
-  │   └── Flow-LLM Router — Cost-optimized routing with analytics
-  │
-  ├── Extension Registry (plugin contract)
-  │   ├── Discovery — scans for ucore-extension.json manifests
-  │   ├── Loading — imports and calls setup(app) on each extension
-  │   └── Routing — delegates /api/* prefixes to extensions
-  │
-  ├── Adaptable (moving to dedicated repos)
-  │   ├── uFlow — workflow engine, runs, logs, task orchestration
-  │   └── uKnowledge — vault search, semantic search, indexing
-  │
-  └── Plugins (udos-* prefix)
-      └── HomeNest/modules/home-ops/udos-home — starter domain plugin module
-
-→ Roundtable MCP → parallel Claude/Gemini/OpenRouter execution
-```
-
-## Repositories
-
-| Repo           | Kind          | Purpose                                    | Location            |
-| -------------- | ------------- | ------------------------------------------ | ------------------- |
-| **uCore**      | host/core     | Platform daemon + extension registry       | `~/Code/uCore`      |
-| **uFlow**      | workflow      | Workflow engine, runs, logs, tasks         | `~/Code/uFlow`      |
-| **uKnowledge** | knowledge     | Vault search, semantic search, indexing | `~/Code/uKnowledge` |
-| **uCode**      | runtime       | Base runtime and core grid/code foundation | `~/Code/uCode`      |
-| **uCode2**     | runtime       | Advanced runtime layer (later extension)   | `~/Code/uCode2`     |
-| **HomeNest**   | plugin (udos) | Home automation + app-layer runtime        | `~/Code/HomeNest`   |
-| **uDocs**      | docs          | Canonical documentation                    | GitHub              |
-
-## Editor Strategy
-
-- Dedicated third-party workspace sync inside uCore is deprecated.
-- Vault content should remain portable and work in standard editors such as
-  Obsidian without uCore-specific lock-in.
-- Primary editing happens in the in-product Markdown editor for first-class
-  document workflows.
-- Task flows should link to markdown specs/docs when deeper implementation
-  details are required.
-
-> During the repo split, uCore keeps **routing adapters**
-> (`app.extensions.adapters/`) as import bridges only.
-> Missing required external repos must fail fast.
-
-## Surfaces (10)
-
-| Surface       | Route                | Description                                                           |
-| ------------- | -------------------- | --------------------------------------------------------------------- |
-| Dashboard     | `/`                  | Main landing, Dev Mode filtering                                      |
-| Intelligence  | `/intelligence`      | Chat, planning, models, agents, budget, and history                    |
-| Snackbar      | `/snackbar`          | Services, feeds, skills, snacks, extensions, logs, and MCP            |
-| Developer     | `/developer`         | Developer tools                                                       |
-| System        | `/system`            | System settings                                                       |
-| Workflow      | `/workflow`          | Workflow builder                                                      |
-| SnackMachine  | `/snackbar?tab=snacks` | Core snack workspace (packaged snacks via SnackMachine extension)   |
-| BrowserUI     | `/browserui`         | Browser automation                                                    |
-| Documentation | `/documentation`     | Docs viewer                                                           |
-| uCode         | `/ucode`             | uCode runtime bridge: GridCore, GridSmith, teletext, terminal widgets |
-
-## Documentation
-
-Canonical docs live in **[uDocs](https://github.com/uDosGo/uDocs)**:
-
-| Section                                                                                   | Description                            |
-| ----------------------------------------------------------------------------------------- | -------------------------------------- |
-| [Architecture](https://github.com/uDosGo/uDocs/blob/main/architecture/overview.md)        | System topology, data flow, security   |
-| [API Reference](https://github.com/uDosGo/uDocs/blob/main/api/rest-api.md)                | All endpoints with examples            |
-| [Runbooks](https://github.com/uDosGo/uDocs/blob/main/runbooks/development.md)             | Setup, deploy, backup, troubleshooting |
-| [Surfaces](https://github.com/uDosGo/uDocs/tree/main/surfaces)                            | All 12 surfaces                        |
-| [Agent Architecture](docs/AGENT_EXECUTION_ARCHITECTURE.md)                              | Guided model routing and orchestration |
-
-Local docs in `docs/` cover vault plates, USX layout, and system specs.
-
-## Key Endpoints
+## Verification
 
 ```bash
-curl http://localhost:8484/api/health          # Health check
-curl http://localhost:8484/api/skills          # 15 skills
-curl http://localhost:8484/api/tools           # 7 tools
-curl http://localhost:8484/api/models          # 4 providers
-curl http://localhost:8484/api/secrets         # Encrypted store
-curl http://localhost:8484/api/mcp/tools       # MCP tools
-curl http://localhost:8484/api/knowledge/workspaces  # Vault workspace bridge
+pnpm build
+pnpm test
+pnpm lint
+pnpm mcp:build
+pnpm mcp:test
 ```
 
-## Status
-
-- **301 backend tests** — all passing
-- **0 TypeScript errors** — clean build
-- **15 built-in skills** — auto-discovered
-- **4 AI providers** — Ollama, OpenRouter, Claude, Gemini
-- **12 surfaces** — Vue 3 + USX layout system
-- **Plates system** — Vault plates, surface templates, destroy patterns
+The official MCP implementation is `backend/app/mcp/udos_mcp`. It is a
+self-hosted stdio gateway with six bounded read-only tools. It is not a second
+orchestration, task, provider, or knowledge system.
+
+## Architecture rules
+
+- `~/Code` is the Developer lane; `~/Vault`, `~/Shared`, and `~/Public` are
+  content lanes.
+- GitHub is the remote source of truth. uFlow owns durable task and evidence
+  state.
+- Provider and budget decisions pass through one governed routing path.
+- Capabilities are registered explicitly and fail closed; loose runtime scripts,
+  fake users, compatibility shims and duplicated MCP facades are unsupported.
+- `Vendor/` is local development research only. Useful components are forked
+  into an active repository before becoming product dependencies.
+- Required extensions fail clearly when unavailable; there are no hidden
+  fallback implementations.
+
+## Current documentation
+
+- [Developer surface](docs/DEVELOPER_SURFACE.md)
+- [Developer GitHub contract](docs/DEVELOPER_GITHUB_CONTRACT.md)
+- [Extension registry](docs/EXTENSION_REGISTRY_SPEC.md)
+- [MCP setup](docs/MCP_SETUP.md)
+- [MCP architecture audit](docs/MCP_ARCHITECTURE_AUDIT_2026-08-19.md)
+- [Surface ownership](docs/SURFACE_OWNERSHIP.md)
+- [Repository ownership boundaries](docs/UCORE_UCODE_ROLE_BOUNDARY.md)
+
+Historical plans and superseded experiments live under `docs/archive/`,
+`docs/archived/`, and `docs/legacy/`; they are not implementation contracts.
 
 ## License
 
-Apache 2.0 — see LICENSE.
+Apache 2.0 — see [LICENSE](LICENSE).
diff --git a/docs/EXTENSION_REGISTRY_SPEC.md b/docs/EXTENSION_REGISTRY_SPEC.md
@@ -282,7 +282,7 @@ required capability paths.
 ## uVector Position (Current)
 
 `uVector` is currently best treated as an **extension-class engine candidate**
-aligned with uCode2/uCode3-era rendering workflows, not as a `udos-*` domain
+aligned with future uCode rendering profiles, not as a `udos-*` domain
 plugin.
 
 Evidence from `uVector` repository:
@@ -296,7 +296,7 @@ Evidence from `uVector` repository:
 
 Current recommended interpretation:
 
-1. uVector aligns with future uCode2/uCode3 and grid-runtime rendering
+1. uVector aligns with future uCode and grid-runtime rendering
    concerns.
 2. uVector may also be consumed by Google/Nano-Banana image-generation flows
    as a conversion/post-processing engine.

diff --git a/docs/README.md b/docs/README.md
@@ -28,40 +28,30 @@
 | [GRID_ALGEBRA_COLUMN_SPECS.md](GRID_ALGEBRA_COLUMN_SPECS.md)     | Responsive grid column algebra                 |
 | [specs/GRIDCORE_VARIABLEIZATION_SPEC.md](specs/GRIDCORE_VARIABLEIZATION_SPEC.md) | `--gridcore-*` variable contract |
 
-## Active Frontend / UI Specs
+## Current Frontend / UI Specs
 
 | Doc                                                                      | Purpose                       |
 | ------------------------------------------------------------------------ | ----------------------------- |
 | [USX_LAYOUT_SYSTEM_SPEC.md](USX_LAYOUT_SYSTEM_SPEC.md)                   | USX layout system             |
 | [FONT_SIZING_STANDARDS.md](FONT_SIZING_STANDARDS.md)                     | Font sizing standards         |
 | [FILEPICKER_SIDEBAR_SPEC.md](FILEPICKER_SIDEBAR_SPEC.md)                 | Filepicker sidebar            |
 | [FILEPICKER_INTEGRATION_STATUS.md](FILEPICKER_INTEGRATION_STATUS.md)     | Filepicker integration status |
-| [MENUBAR_UNIFICATION_PLAN.md](MENUBAR_UNIFICATION_PLAN.md)               | Menubar unification           |
-| [FRONTEND_CONSOLIDATION_PLAYBOOK.md](FRONTEND_CONSOLIDATION_PLAYBOOK.md) | Frontend consolidation        |
-| [VUE_REFACTOR_SURFACE_TAGGING.md](VUE_REFACTOR_SURFACE_TAGGING.md)       | Vue refactor surface tags     |
 | [SURFACE_OWNERSHIP.md](SURFACE_OWNERSHIP.md)                             | Canonical route and tab ownership |
 | [UDOS_HOME_MIGRATION.md](UDOS_HOME_MIGRATION.md)                         | Runtime/vault boundary and safe migration |
 | [ECOSYSTEM_STORAGE_ARCHITECTURE.md](ECOSYSTEM_STORAGE_ARCHITECTURE.md)   | Canonical storage, credentials and drift controls |
 | [WORKSTATION_MIGRATION_2026-08-18.md](WORKSTATION_MIGRATION_2026-08-18.md) | Migration record, verification and rollback boundary |
-| [AGENT_EXECUTION_ARCHITECTURE.md](AGENT_EXECUTION_ARCHITECTURE.md)       | Intention routing, providers, orchestration and controls |
-| [SKILLS_AUDIT_2026-08-18.md](SKILLS_AUDIT_2026-08-18.md)                 | Skill disposition and remediation sequence |
 
 ## Active Developer / Dev Mode Specs
 
 | Doc                                                                                                        | Purpose                                                  |
 | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
 | [DEVELOPER_SURFACE.md](DEVELOPER_SURFACE.md)                                                               | Current Developer Surface UX, lanes, controls, and APIs  |
-| [specs/ECOSYSTEM_EXTENDED_DEV_FLOW_2026-07-31.md](specs/ECOSYSTEM_EXTENDED_DEV_FLOW_2026-07-31.md)         | Extended ecosystem flow, repo ownership, and sprint plan |
-| [specs/AUTONOMOUS_DEV_ROUNDS_RUNBOOK.md](specs/AUTONOMOUS_DEV_ROUNDS_RUNBOOK.md)                           | Stable autonomous dev round lifecycle and hard gates     |
-| [QQCODE_TUI_INTEGRATION.md](QQCODE_TUI_INTEGRATION.md)                                                     | QQCode TUI integration                                   |
-| [OPTIMIZED_WORKFLOW.md](OPTIMIZED_WORKFLOW.md)                                                             | Optimized workflow                                       |
 | [DOCLANG_BRIDGE_EXPORT_SPEC.md](DOCLANG_BRIDGE_EXPORT_SPEC.md)                                             | DocLang bridge export                                    |
 | [TERMINAL_TELETEXT_GRID_WORK_TAG.md](TERMINAL_TELETEXT_GRID_WORK_TAG.md)                                   | Terminal/teletext grid work tag                          |
 
-## Active Task / Planning Trackers
+## Task ownership
 
 - `uFlow` — canonical workflow and task owner (`$UDOS_HOME/flow/tasks`)
-- `docs/CONSOLIDATION_PLAN.md` — docs consolidation tracker (kept for reference)
 
 ## Archive
 

diff --git a/docs/SETTINGS_ARCHITECTURE_2026.md b/docs/SETTINGS_ARCHITECTURE_2026.md
@@ -10,7 +10,7 @@ The settings system has three tiers of configuration, each backed by different p
 
 ## Layer 1: Global & User Settings (System Surface)
 
-**Location**: `http://localhost:5173/system?tab=global-settings` and `?tab=user-settings`
+**Location**: `http://localhost:5175/system?tab=global-settings` and `?tab=user-settings`
 
 **Component**: `frontend-vue/src/surfaces/system/SystemSurface.vue`
 
@@ -75,7 +75,7 @@ interface UserSettings {
 
 ## Layer 3: Developer Settings (Developer Surface)
 
-**Location**: `http://localhost:5173/developer?tab=settings`
+**Location**: `http://localhost:5175/developer`
 
 **Component**: `frontend-vue/src/surfaces/developer/panels/SettingsPanel.vue`
 
@@ -130,4 +130,4 @@ These are developer-facing controls (USX typography/spacing, GridCore grid algeb
 - [ ] Settings profiles (saved configurations)
 - [ ] Keyboard shortcuts for common settings
 - [ ] Accessibility settings panel (contrast, focus indicators)
-- [ ] S-page/P-page content modules (Wave 2)
+- [ ] S-page/P-page content modules (Wave 2)
diff --git a/docs/SNACKS_SYSTEM_SPEC.md b/docs/SNACKS_SYSTEM_SPEC.md
@@ -62,7 +62,7 @@ backend/app/menu/unified_menu_simple.py now:
 - executes system snack actions via /api/snacks/system/{id}/run
 - renders multi-action submenu entries
 
-**Note**: Full snack management is available in the SnackMachine surface (http://localhost:5173/snackmachine).
+**Note**: Snack management is available in Snackbar (`http://localhost:5175/snackbar?tab=snacks`).
 
 ## Dependencies
 

diff --git a/docs/VAULT_BINDER_WORKFLOW_INTEGRATION.md b/docs/VAULT_BINDER_WORKFLOW_INTEGRATION.md
@@ -361,7 +361,7 @@ uCore enforces a strict separation between user content and system code:
 ### Boundary Rules
 
 1. **User Lane agents** (AssistUI chat) work only on vault content, binders, docs, and uCode (BASIC) files. They never touch the system codebase.
-2. **Developer Lane agents** (Hivemind, Roundtable, Cline) work only on the codebase. They never touch user vaults unless explicitly directed.
+2. **Developer Lane tools** work only on the codebase. They never touch user vaults unless explicitly directed.
 3. The Assistant should ask which lane the user intends before performing ambiguous actions.
 4. The Developer Surface is hidden by default (can be enabled in Settings).
 5. The default lane in AssistUI is **User**.
@@ -391,4 +391,4 @@ uCore enforces a strict separation between user content and system code:
 - [SPOOL_SPEC.md](SPOOL_SPEC.md) — Activity feed and spool logging
 - [DEVELOPER_SURFACE.md](DEVELOPER_SURFACE.md) — Developer Surface documentation
 - [SETTINGS_ARCHITECTURE_2026.md](SETTINGS_ARCHITECTURE_2026.md) — Settings system
-- [FEATURE_SPEC_ASSISTUI_DEVELOPER_CHAT_LANE_SEPARATION.md](FEATURE_SPEC_ASSISTUI_DEVELOPER_CHAT_LANE_SEPARATION.md) — Chat lane separation spec
+- [FEATURE_SPEC_ASSISTUI_DEVELOPER_CHAT_LANE_SEPARATION.md](FEATURE_SPEC_ASSISTUI_DEVELOPER_CHAT_LANE_SEPARATION.md) — Chat lane separation spec
diff --git a/docs/AGENT_EXECUTION_ARCHITECTURE.md → ...GENT_EXECUTION_ARCHITECTURE_2026-08-18.md b/docs/AGENT_EXECUTION_ARCHITECTURE.md → ...GENT_EXECUTION_ARCHITECTURE_2026-08-18.md
@@ -1,6 +1,6 @@
 # Agent Execution Architecture
 
-**Status:** Canonical direction
+**Status:** Superseded historical direction
 
 **Updated:** 2026-08-18
 

diff --git a/...ECOSYSTEM_EXTENDED_DEV_FLOW_2026-07-31.md → ...ECOSYSTEM_EXTENDED_DEV_FLOW_2026-07-31.md b/...ECOSYSTEM_EXTENDED_DEV_FLOW_2026-07-31.md → ...ECOSYSTEM_EXTENDED_DEV_FLOW_2026-07-31.md
@@ -1,6 +1,6 @@
 # Ecosystem Extended Dev Flow (2026-07-31)
 
-Status: Active planning baseline
+Status: Superseded planning record
 Owner: uCore host shell + companion plugin/extension repos
 Purpose: keep core infrastructure simple and robust while enabling focused plugin waves.
 

diff --git a/docs/MENUBAR_UNIFICATION_PLAN.md → docs/archive/MENUBAR_UNIFICATION_PLAN.md b/docs/MENUBAR_UNIFICATION_PLAN.md → docs/archive/MENUBAR_UNIFICATION_PLAN.md
@@ -1,4 +1,4 @@
-# macOS Menu Bar Unification Plan
+# Archived — macOS Menu Bar Unification Plan
 
 **Date:** 2026-06-27  
 **Status:** ✅ Complete  

diff --git a/docs/PLATES_SYSTEM_SPEC.md → docs/archive/PLATES_SYSTEM_SPEC.md b/docs/PLATES_SYSTEM_SPEC.md → docs/archive/PLATES_SYSTEM_SPEC.md
@@ -1,7 +1,7 @@
 # uCore Plates System Specification
 
 > **Version:** 1.0  
-> **Status:** Draft  
+> **Status:** Superseded draft  
 > **Scope:** Skills, Snacks, MCP Tools, Hivemind Patterns, Variables/Secrets, CSS/USX  
 > **Naming:** "Plates" — canonical, versioned, recoverable blueprints (like printing plates)
 

diff --git a/docs/SKILLS_AUDIT_2026-08-18.md → docs/archive/SKILLS_AUDIT_2026-08-18.md b/docs/SKILLS_AUDIT_2026-08-18.md → docs/archive/SKILLS_AUDIT_2026-08-18.md
@@ -1,6 +1,6 @@
 # Skills Audit — 2026-08-18
 
-**Status:** Active remediation
+**Status:** Completed/superseded remediation record
 
 **Observed registry before remediation:** 53 executable Skills, including one user example