my-crew 0.1.0__tar.gz

my_crew-0.1.0/.dockerignore

@@ -0,0 +1,32 @@
+# Build context = the repo; keep user data, secrets, and heavyweight dev dirs out.
+# NOTE dockerignore semantics: patterns are anchored to the context root (unlike
+# .gitignore) — nested matches need the `**/` prefix. Last matching pattern wins.
+.git
+.venv
+.pytest_cache
+**/__pycache__
+**/*.pyc
+dist
+plans
+.data
+.demo-backup
+.mcp-servers
+node_modules
+web/node_modules
+web/dist
+
+# User data / secrets (never bake into an image) — recursive on purpose: the
+# compose flow writes deploy/docker/my-crew.env with REAL secrets next to the
+# Dockerfile, and a rebuild must never copy it in.
+**/.env
+**/.env.*
+**/*.env
+!.env.example
+!deploy/docker/my-crew.env.example
+registry.yaml
+company.yaml
+company-docs
+.setup-complete
+profiles/*
+!profiles/default
+!profiles/templates

my_crew-0.1.0/.env.example

@@ -0,0 +1,125 @@
+# Copy to .env and fill in. .env is gitignored — never commit real values.
+# ALL secrets live in THIS ONE agent .env. The agent (MCP client) reads them and
+# injects them into each MCP server's subprocess env when it spawns the server
+# (node dist/index.js). There is no separate per-server .env. GitHub uses `gh auth login`.
+
+# --- Paths ---
+# Root for user state (.env, registry.yaml, company.yaml, profiles/, company-docs/,
+# .data/). Default: the repo checkout when running from git, else ~/.my-crew for an
+# installed package. Set to relocate all state explicitly.
+# MY_CREW_HOME=~/.my-crew
+
+# --- LLM provider (OpenRouter, OpenAI-compatible) ---
+OPENROUTER_API_KEY=
+OPENROUTER_MODEL=minimax/minimax-m2.7
+# v4 M9 (optional): fallback chain, comma-separated, tried in order on 402/429/5xx/
+# timeout/empty. Unset = single model (pre-v4 behavior). Budget cap still supreme.
+# OPENROUTER_MODEL_CHAIN=minimax/minimax-m2.7,qwen/qwen-3.7
+# Fallback model if the default underperforms: qwen/qwen-3.7
+OPENROUTER_REFERER=https://github.com/local/my-project-manager
+OPENROUTER_TITLE=my-project-manager
+
+# --- Guardrails ---
+# DRY_RUN=true -> Action Gateway logs intended writes instead of posting them.
+# Set to false to actually post to Slack.
+DRY_RUN=true
+# Kill switch: true -> gateway refuses ALL mutations (read + log only).
+AGENT_WRITE_DISABLED=false
+# Trust mode (v30): autonomous (default) -> agent actions run immediately with an
+# audit record; guarded -> sensitive (Lớp B) actions queue for human approval.
+# Per-agent override: safety.trust_mode in profile.yaml. Lớp A hard-deny, audit,
+# dry-run and the kill switch apply in BOTH modes.
+TRUST_MODE=autonomous
+# Monthly OpenRouter spend cap (USD). Hard-stop at 100%, warn at the ratio below.
+MONTHLY_BUDGET_USD=50
+BUDGET_WARN_RATIO=0.8
+
+# --- Atlassian / Jira (agent injects these into the Jira MCP server subprocess) ---
+ATLASSIAN_SITE_NAME=
+ATLASSIAN_USER_EMAIL=
+ATLASSIAN_API_TOKEN=
+
+# --- Slack (agent injects these into the Slack MCP server subprocess) ---
+# Browser-token auth -- BROAD scope, handle with care.
+SLACK_XOXC_TOKEN=
+SLACK_XOXD_TOKEN=
+SLACK_TEAM_DOMAIN=
+
+# --- Report targets ---
+JIRA_PROJECT_KEY=
+GITHUB_REPO=
+SLACK_REPORT_CHANNEL=
+
+# --- Risk thresholds (defaults shown) ---
+PR_STALE_DAYS=7
+BLOCKER_LABEL_SUBSTRING=block
+
+# --- Optional: override MCP server entry paths ---
+# Defaults: ~/workspace/jira-cloud-mcp-server/<entry>, ~/workspace/slack-browser-mcp-server/<entry>
+# JIRA_MCP_DIST=
+# SLACK_MCP_DIST=
+
+# --- M3-P11 (C3): optional Linear integration (config-driven extra MCP server) ---
+# Declare `integrations.linear` in profile.yaml; the agent spawns the stdio server
+# (@tacticlaunch/mcp-linear) and reads issues/projects. Writes (createComment) stay
+# behind the Action Gateway (Lop B approval). Token is read here, never in profile.yaml.
+# LINEAR_MCP_DIST=
+# LINEAR_API_TOKEN=
+
+# --- M3-P11 (D2): optional Email (SMTP) delivery channel ---
+# Declare `smtp:` in profile.yaml (or set SMTP_HOST). Every email is sent through the
+# Action Gateway and requires Lop B human approval. Password is read here, never in yaml.
+# SMTP_HOST=smtp.gmail.com
+# SMTP_PORT=587
+# SMTP_USER=
+# SMTP_PASSWORD=          # app password; env-only, never committed in a profile
+# SMTP_FROM_ADDR=
+# SMTP_USE_TLS=true
+# SMTP_RECIPIENTS=        # comma-separated
+
+# --- v6 M13: optional per-agent Telegram bot identity ---
+# Each agent = its OWN bot (create via @BotFather). Declare `telegram:` in the agent's
+# profile.yaml with `bot_token_env` naming a var here — one var per agent, value env-only.
+# <AGENT>_TELEGRAM_BOT_TOKEN=
+
+# --- Confluence (Slice 2: detail report). Reuses Atlassian token above. ---
+CONFLUENCE_SPACE_KEY=
+CONFLUENCE_SPACE_ID=
+
+# --- Phase 2: Lớp B (channels needing human approval before posting) ---
+# Comma-separated channel IDs treated as external/stakeholder. Posting to these
+# is queued for approval (cli approve), not auto-executed. Empty = none external.
+SLACK_EXTERNAL_CHANNELS=
+
+# --- Phase 3: OKR / objective tracking ---
+# Confluence page (id) holding the OKR table: columns Objective | Key Result |
+# Epic Key(s) | Weight. Empty = OKR features off (report --okr errors, weekly
+# section omitted). An Objective rolling up below the threshold (fraction 0..1)
+# is flagged "at risk".
+OKR_CONFLUENCE_PAGE_ID=
+OKR_BEHIND_THRESHOLD=0.5
+
+# --- Phase 4: Resource (capacity) + Cost reporting ---
+# Overload threshold: an assignee is "overloaded" if their open-issue count
+# exceeds team_mean × this ratio (1.5 ⇒ >150% of the team average).
+RESOURCE_OVERLOAD_RATIO=1.5
+# Average labor cost per open issue, USD, for a rough labor estimate.
+# 0 ⇒ labor estimate omitted from the report (only the real LLM budget shows).
+LABOR_COST_PER_ISSUE=0
+
+# --- Phase 5: Audience-split (external/stakeholder reports) ---
+# The single Slack channel external/stakeholder reports post to (--audience external).
+# MUST also be listed in SLACK_EXTERNAL_CHANNELS so the post routes through Lớp B
+# human approval (otherwise it would auto-post to stakeholders without review).
+SLACK_STAKEHOLDER_CHANNEL=
+
+# --- v6 M16: web dashboard auth (single-user session) ---
+# Generate the hash:   uv run python -m src.entrypoints.mpm web hash-password
+# Generate the secret: uv run python -m src.entrypoints.mpm web gen-secret
+# When WEB_AUTH_PASSWORD_HASH is UNSET, the dashboard runs with NO auth (localhost dev only).
+# Binding a non-loopback BIND_HOST while auth is OFF is REFUSED at startup.
+# WEB_AUTH_USERNAME=admin
+# WEB_AUTH_PASSWORD_HASH=
+# WEB_SESSION_SECRET=
+# BIND_HOST=127.0.0.1        # 0.0.0.0 for LAN — only with auth configured above
+# PORT=8765

my_crew-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,64 @@
+# CI: the suite is secret-free by design (tests/conftest.py isolates env + tmp dirs),
+# so every job runs on plain PyPI/npm with no credentials.
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  backend:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --extra deep
+      - run: uv run ruff check .
+      - run: uv run pytest -q
+
+  frontend:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: web
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+      - run: npm ci
+      # Build for real, not just --noEmit: a stale committed dist bit us before
+      # (v32); tsc -b + vite build is the honest gate. NOTE: this does NOT diff the
+      # rebuilt output against the committed dist (vite hash stability across
+      # runners is unverified) — docs/releasing.md step 2 is the stale-dist guard.
+      - run: npx tsc -b
+      - run: npm test
+      - run: npm run build
+
+  wheel:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv build
+      # The wheel must carry the shipped resources and the FE bundle — a wheel
+      # without them installs a my-crew that cannot seed a fresh home.
+      - name: verify wheel contents
+        run: |
+          test "$(unzip -l dist/*.whl | grep -c _shipped/)" -ge 60
+          test "$(unzip -l dist/*.whl | grep -cE 'static/app/')" -ge 10
+      - name: smoke-install from the wheel
+        run: |
+          python -m venv /tmp/v && /tmp/v/bin/pip -q install dist/*.whl
+          MY_CREW_HOME=/tmp/crew-home /tmp/v/bin/my-crew --version
+          MY_CREW_HOME=/tmp/crew-home /tmp/v/bin/my-crew agent list

my_crew-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,47 @@
+# Release: build from the tag, publish to PyPI via OIDC trusted publishing (no stored
+# token — register this repo+workflow as a trusted publisher for project `my-crew` on
+# pypi.org first; see docs/releasing.md). workflow_dispatch = build-only rehearsal.
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv build
+      - name: verify wheel contents
+        run: |
+          test "$(unzip -l dist/*.whl | grep -c _shipped/)" -ge 60
+          test "$(unzip -l dist/*.whl | grep -cE 'static/app/')" -ge 10
+      - uses: actions/upload-artifact@v4
+        with:
+          name: packages
+          path: dist/
+
+  publish:
+    # Tag pushes only — a workflow_dispatch run stops at the build rehearsal.
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # OIDC — the only credential involved
+      contents: write  # the GitHub Release below
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: packages
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

my_crew-0.1.0/.gitignore

@@ -0,0 +1,63 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.ruff_cache/
+
+# venv (uv-managed)
+.venv/
+
+# Secrets — never commit
+.env
+*.env
+!.env.example
+
+# Runtime data: audit log, checkpoints, budget (see plan .data/ decision)
+.data/
+
+# Company Docs library (v7 M19): CEO-curated documents = local user data, restored
+# from backup (backup.sh covers it), never committed.
+company-docs/
+
+# Per-agent profiles: only the `default` template is committed (holds no secrets,
+# only token_env NAMES). Real per-agent profiles stay local.
+profiles/*
+!profiles/default/
+!profiles/default/**
+# Staff templates: shipped prefill source for the CreateAgent wizard, not a per-agent
+# runtime profile — committed like profiles/default/.
+!profiles/templates/
+!profiles/templates/**
+
+# Company identity (name + coordinator + team-task cap) — per-install user data like
+# real profiles; load_company() degrades safely when absent on a fresh clone.
+company.yaml
+
+# Agent tooling / instructions — not part of the published project
+.claude/
+AGENTS.md
+CLAUDE.md
+
+# Internal working artifacts — not part of the published project
+plans/
+docs/references/
+.dandori-agent
+
+# Frontend (M4): ignore deps + the in-web build cache, but COMMIT the served dist
+# at my_crew/server/static/app/ (the "FastAPI serves static, zero Node step" property).
+web/node_modules/
+web/dist/
+
+# MCP servers installed from npm by the installer (P4) into a repo-local prefix —
+# never committed, re-created by deploy/install.sh.
+.mcp-servers/
+
+# OS
+.DS_Store
+.setup-complete
+.env.bak
+# demo-mode swap backup (chứa data THẬT khi demo đang bật — tuyệt đối không commit)
+.demo-backup/
+# v18: registry is user data (the CEO's real team) — template is registry.example.yaml
+/registry.yaml

my_crew-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

my_crew-0.1.0/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · Versioning: semver.
+Development history at finer grain lives in [docs/journals/](docs/journals/).
+
+## [0.1.0] — 2026-07-18
+
+First installable release. Everything below existed as a clone-and-run system built
+across v1–v50 (see journals); 0.1.0 packages it as a product.
+
+### Added
+- `my-crew` console script (PyPI package `my-crew`): `--help`, `--version`, and the
+  full command surface — `quickstart`, `crew init`, `serve`, `doctor`, `upgrade`,
+  `agent *`, `web hash-password`, `sandbox prepull`.
+- `my-crew serve`: foreground web + coordinator supervisor for Docker Compose,
+  systemd, or a plain terminal. `deploy/docker/` ships a Dockerfile + compose file.
+- `MY_CREW_HOME`: user state (.env, registry, profiles, data) resolves to the env
+  var, else the git checkout, else `~/.my-crew`. Shipped starter profiles seed into
+  a fresh home on first run.
+- The wheel bundles the web dashboard (no Node needed to install) and the shipped
+  resources (starter profiles, templates, domain packs, examples).
+- GitHub Actions CI (secret-free test suite, ubuntu + macos) and an OIDC-based
+  PyPI release pipeline.
+
+### Core (pre-0.1.0, summarized)
+- Autonomy-first agent harness on LangGraph: every write flows through the Action
+  Gateway — hard-coded red lines (Lớp A), autonomous-vs-guarded trust modes,
+  kill-switch, dry-run default, dedup, rate-limit, immutable audit log.
+- Multi-agent virtual office: browser dashboard + 3D office, one-click staff
+  templates, chat-ops, team tasks with review steps, per-task cost tracking.
+- Integrations via MCP: Jira, Confluence, Slack (+ GitHub via `gh`), layered
+  memory, budget caps, scheduler with per-agent cron.
+
+### Known limitations
+- The `deep` sandbox tier (`pip install my-crew[deep]`) needs a Docker daemon and
+  is not available *inside* the provided container image.
+- The 3 MCP servers require Node at runtime (prepulled in the Docker image;
+  installed by `deploy/install.sh` on native installs).

my_crew-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contributing
+
+## Dev setup
+
+```bash
+git clone git@github.com:phuc-nt/my-crew.git && cd my-crew
+uv sync --extra deep        # deep = optional Docker-sandbox tier (needs Docker to run, not to test)
+uv run pytest -q            # 2364+ BE tests — no secrets, no network, no Docker required
+uv run ruff check .
+cd web && npm install && npm test   # 201 FE tests
+```
+
+A git checkout keeps all user state repo-local (`.env`, `registry.yaml`,
+`profiles/`, `.data/`) — `MY_CREW_HOME` docs: see the deployment guide.
+
+## Rules of the road
+
+- **The test suite must stay secret-free.** Any test that needs a real key,
+  network, or Docker daemon gets a `skipif` gate. CI runs the whole suite on
+  clean runners.
+- **The Action Gateway is the invariant.** Changes that add a write path must
+  route it through the gateway; changes to Lớp A/Lớp B semantics need an
+  explicit maintainer decision, not a drive-by refactor.
+- **Conventional commits** (`feat:`, `fix:`, `refactor:` …), no AI references.
+- Python: ruff-clean, snake_case, type hints on public functions; line length 100.
+- FE: TypeScript strict; build for real (`npm run build`) when the dist matters —
+  the served bundle at `my_crew/server/static/app/` is committed.
+- Docs: user-facing behavior changes update `docs/`; development narrative goes
+  to `docs/journals/`.
+
+## Releases
+
+Maintainer-driven; see [docs/releasing.md](docs/releasing.md).

my_crew-0.1.0/HANDOVER.md

@@ -0,0 +1,133 @@
+# HANDOVER — my-crew
+
+Bạn là agent/đội mới nhận repo này để **refactor + phát triển tiếp**. File này là điểm
+vào DUY NHẤT: đọc xong bạn biết đọc gì tiếp. Không cần biết toàn bộ quá trình xây dựng —
+chỉ cần đủ context để làm tiếp an toàn.
+
+---
+
+## 1. Sản phẩm là gì (30 giây)
+
+Một **đội nhân sự ảo AI** cho công ty một-người. CEO (không kỹ thuật) giao việc qua web/
+Telegram; các agent tự làm việc PM/nội dung/nghiên cứu/phân tích/kiểm định, đọc dữ liệu
+thật từ Jira·GitHub·Confluence·Slack, và *tự hành động* (viết báo cáo, tạo trang, cảnh báo).
+
+**Triết lý cốt lõi — thuộc nằm lòng:** *tự chủ về TỐC ĐỘ, không bao giờ tự chủ về TRÁCH
+NHIỆM.* Mọi hành động ghi ra ngoài công ty đi qua MỘT cửa kiểm soát (Action Gateway);
+việc mất-dữ-liệu/lộ-bí-mật bị chặn cứng, LLM không vượt được kể cả khi "muốn".
+
+## 2. Tech stack
+
+- **Backend**: Python ≥3.12, quản lý bằng **uv**. LangGraph (agent graph). FastAPI + SSE.
+  SQLite (WAL) cho state. Không dùng ORM.
+- **Frontend**: React 19 + TypeScript + Vite; react-three-fiber/three cho màn 3D "Văn phòng".
+  Build dist commit vào `src/server/static/app/` (server serve tĩnh).
+- **Tích hợp ngoài**: MCP servers (Jira/Confluence/Slack) + `gh` CLI (GitHub) + `gws` CLI
+  (Google Sheets, hr-pack). LLM qua OpenRouter.
+- **Test**: `uv run pytest` (~1706 BE) · `cd web && npx vitest run` (~177 FE) · `npx tsc --noEmit`.
+
+## 3. Đọc theo thứ tự này
+
+| # | File | Để biết | Ưu tiên |
+|---|------|---------|---------|
+| 1 | **`CLAUDE.md`** | Luật làm việc trong repo (workflow, quy tắc code, commit, hook privacy) | BẮT BUỘC |
+| 2 | **`.claude/rules/*.md`** | Chi tiết: development-rules, primary-workflow, orchestration, review | BẮT BUỘC |
+| 3 | **`docs/project-overview-pdr.md`** | Vision, vấn đề, phạm vi, yêu cầu — VÌ SAO có sản phẩm | BẮT BUỘC |
+| 4 | **`docs/system-architecture.md`** | Kiến trúc as-built v18 (sơ đồ, thành phần, luồng dữ liệu) | BẮT BUỘC |
+| 5 | **`docs/action-gateway-explainer.md`** | Mô hình an toàn (Action Gateway) — trái tim sản phẩm | BẮT BUỘC |
+| 6 | **`docs/codebase-summary.md`** | Bản đồ "cái gì ở file nào" + quyết định theo mốc | BẮT BUỘC |
+| 7 | `docs/uat-theo-user-story.md` | Sản phẩm LÀM ĐƯỢC GÌ (7 epic, 22 story) — spec hành vi | Cao |
+| 8 | `docs/project-roadmap.md` | Đã làm gì + việc nên làm tiếp | Cao |
+| 9 | `docs/deployment-guide.md` | Cài / chạy / backup | Khi deploy |
+| 10 | `docs/code-standards.md`, `docs/design-guidelines.md` | Chuẩn code + UI | Vừa |
+| 11 | `docs/journals/*`, `plans/*` | Lịch sử từng vòng — chỉ tra khi cần "vì sao quyết định X" | Tra cứu |
+
+> `README.md` cho người học "cách build agent có guardrail" (vision, không phải map kiến
+> trúc hiện tại). `docs/huong-dan-su-dung.md` là hướng dẫn tiếng Việt cho CEO (người dùng
+> cuối). `docs/archive/` chứa tài liệu cũ (v1/v2, phỏng vấn, so-sánh-kiến-trúc) — CHỈ tra
+> khi cần lịch sử.
+
+## 4. Bản đồ code (nơi bắt đầu khi sửa)
+
+```
+src/
+  agent/        LangGraph graphs + nodes. LÕI: coordinator_graph.py (ticker điều phối),
+                team_task_graph.py (chạy 1 bước việc), task_decomposition.py (chia việc),
+                review_graph.py (soát chéo), ops_*.py (lệnh CEO: giao/chỉnh việc)
+  actions/      Action Gateway (action_gateway.py) + hard_block.py (Lớp A chặn cứng) +
+                *_write.py (handler ghi ngoài, đều qua gateway)
+  runtime/      service.py (daemon điều phối/scheduler), worker.py (chạy 1 agent),
+                team_task_store.py (SQLite state đội), office_room_*.py (feed realtime)
+  server/       FastAPI app.py + routes_*.py + office_event_projection.py (PII firewall)
+  llm/ config/ profile/ skills/ packs/ company_docs/ reporting/ audit/  — hỗ trợ
+web/src/
+  views/office-unified/  Màn chính "Văn phòng" (3 cột: phòng việc | hoạt động | kết quả)
+  views/office-3d/       Cảnh 3D (r3f), reducer sự kiện → trạng thái bàn
+  views/                 Team, Work (Duyệt), Settings, Chat…
+```
+
+Entry points: web `python -m src.server.app` (hoặc `main()` trong app.py) · daemon điều
+phối `python -m src.runtime.service` · CLI `python -m src.entrypoints.mpm`.
+
+## 5. BẤT BIẾN — đừng phá khi refactor (đọc kỹ)
+
+Đây là các ràng buộc an toàn đã được red-team + E2E bảo vệ qua nhiều vòng. Sửa mà không
+hiểu chúng = tạo lỗ hổng. Chi tiết trong codebase-summary "THE INVARIANT":
+
+1. **Action Gateway = cửa DUY NHẤT ra ngoài.** Mọi ghi external (Slack/Jira/Confluence/
+   email) qua gateway → allowlist default-deny + Lớp A hard-block. Thêm handler ghi mới
+   PHẢI đi qua đây, không đi tắt.
+2. **Ghi ra ngoài = Lớp B (chờ CEO duyệt).** Không tự chạy trừ khi trust-ladder bật.
+3. **PII firewall cho office events** (`office_event_projection.py`): allowlist theo kind
+   AT WRITE TIME. Không nhét nội dung tự do (tài liệu, câu trả lời đầy đủ) vào room event.
+4. **Hash-bind khi giao/chỉnh việc**: CEO xác nhận kế hoạch → hash khóa; `_verify_plan_hash`
+   băm lại mỗi tick chống tamper. `room_id`/`pic_id`/`acceptance` là METADATA NGOÀI hash
+   (nếu thêm field vào step, hỏi: "nó có va vào hash-check này không?").
+5. **Cross-process isolation (khóa từ v12)**: KHÔNG chạy orchestration graph xuyên process.
+   Điều phối = ticker (poll ngắn/1-hành-động/thoát) + store + lease. Không nhúng ticker
+   vào web app.
+6. **registry.yaml = USER-DATA (gitignored từ v18)** — KHÔNG BAO GIỜ `git checkout
+   registry.yaml` / không add. Template committed là `registry.example.yaml`.
+
+## 6. Quy trình làm việc (repo dùng skill-driven workflow)
+
+Repo này phát triển theo vòng: **brainstorm → plan → red-team plan → cook (implement) →
+review → E2E thật (browser + LLM thật) → docs/journal → commit**. Bằng chứng: `plans/` +
+`docs/journals/`. Bạn KHÔNG bắt buộc theo hệt, nhưng 2 điều nên giữ:
+- **Red-team plan TRƯỚC khi code** — nhiều Critical được bắt ở tầng plan (rẻ), xem các
+  report `plans/*/reports/from-code-reviewer-to-planner-*`.
+- **E2E trên đường thật** — "suite xanh ≠ chạy được" đã xảy ra 2 lần (feature dead dù
+  test xanh vì test tự set điều kiện prompt/đường thật không tạo ra). Test bằng browser +
+  ticker + LLM thật, soi DB.
+
+## 7. Chạy thử tại chỗ
+
+```bash
+uv sync
+cd web && npm install && npm run build && cd ..     # build FE (dist đã commit sẵn)
+PORT=8765 uv run python -c "from src.server.app import main; main()" &   # web
+uv run python -m src.runtime.service &                                   # điều phối
+# mở http://127.0.0.1:8765  (auth OFF khi localhost + chưa đặt password)
+```
+
+Cần data + đội mẫu để thử ngay: `scripts/demo-mode.sh on` (tắt: `off` — trả data thật
+nguyên vẹn). Đội thật cần ≥1 coordinator + vài agent office trong `registry.yaml` +
+service chạy, nếu không màn Văn phòng hiện banner đỏ "bộ điều phối chưa chạy".
+
+## 8. Nợ kỹ thuật & việc nên làm tiếp (bàn giao trung thực)
+
+- **`docs/codebase-summary.md`** phần thân vẫn dài theo dòng lịch sử v1→v18 — bản đồ
+  chính xác nhưng nên gộp phần cũ thành mục ngắn (header đã đồng bộ v18).
+- **Cải thiện đã ghi nhận từ UAT v17/v18** (chưa làm): xem
+  `plans/260711-0711-.../reports/uat-260711-0908-*findings*.md` + `docs/project-roadmap.md`
+  §"Việc nên làm tiếp" — vd hr/sales-pm là hồ sơ agent mồ côi chưa đăng ký; web_search cần key.
+- Nhật ký/plan rất nhiều (67 journal, 22 plan) — là lịch sử, KHÔNG cần đọc để làm tiếp;
+  tra khi cần "vì sao quyết định X".
+
+## 9. Không được làm
+
+- Không commit secrets/.env/token/private key/db creds/personal data.
+- Không sửa skills trong `~/.claude/skills` (sửa bản trong repo nếu được yêu cầu).
+- Không dùng prefix `chore`/`docs` cho commit thay đổi thư mục `.claude/`.
+- `company.yaml`, `.data/`, `registry.yaml`, hồ sơ trong `profiles/<id>` = user-data
+  (gitignored) — không commit.