diff --git a/AGENTS.md b/AGENTS.md
index b0375f1..8a520a3 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -6,8 +6,10 @@ This file carries only what applies to **every** session. Setup, prerequisites,
 
 ## Structure
 
-- `plugins/` — six installable plugin units, each an apm package (`apm.yml` + `.apm/`). Root `apm.yml` declares all six as `dependencies.apm`; `apm install` deploys them into `.claude/skills/` and `.claude/agents/`, both gitignored install output.
-- `providers/claude-code/` — Claude Code adapter, deployed to `~/.claude/` via `scripts/install.sh`.
+- `plugins/<name>/.apm/` is the only authoring source for plugin content. `.claude/skills/` and `.claude/agents/` are gitignored `apm install` output — never edit them.
+- `providers/claude-code/` is the Claude Code adapter, deployed to `~/.claude/` by `scripts/install.sh`.
+
+Repo layout table: `README.md`. Deployment mechanics and plugin boundaries: `docs/spec/architecture.md`.
 
 ## Prefer plugin skills over raw shell
 
diff --git a/docs/VISION.md b/docs/VISION.md
index b605996..4025d2c 100644
--- a/docs/VISION.md
+++ b/docs/VISION.md
@@ -48,18 +48,10 @@ Browse, edit, and configure AI development config through a proper product UI.
 
 **Design principle:** This is a product, not a file browser. Users never see git operations, file paths, or commit messages. The UI presents domain concepts (skills, workflows, agents, providers) and handles persistence silently. Any feature that exposes git internals to the user is out of scope.
 
-**Architecture:**
-- Stack: React + TypeScript + Vite (frontend), Node.js + Fastify + TypeScript (backend), PostgreSQL (introduced only when a specific feature requires state with no natural home in git)
-- Stack rationale: single language across the full stack keeps the codebase navigable for junior developers and AI coding agents; TypeScript's explicit types make intent clear without comments; React → React Native is the cleanest path to mobile in Phase 3; `simple-git` covers all required git operations without needing a Python backend
-- Git operations via `simple-git`; git repo stays the source of truth
-- Deployment: Docker (Nginx + Node containers), k8s-ready
-- Hosting: self-hosted first, cloud-hosted option later
-- Users: solo-first, multi-user-ready data model from day one
+**Scope:** self-hosted first, cloud-hosted option later; solo-first, with a multi-user-ready data model from day one. The git repo stays the source of truth. Stack, framework and deployment choices belong to that product's own repo, not here.
 
 **Start trigger:** when the plugin content model and sync tooling are stable. Full content model must be stable before building a UI over it.
 
-**Mobile/desktop (Phase 3):** React → React Native for mobile; Tauri to wrap the web app for desktop.
-
 ### Phase 2 — Agent & Fleet Management
 
 Runtime orchestration: push config updates to machines, see running agents, manage task queues and outputs across a fleet of machines and projects.