@ngocsangairvds/vsaf 4.0.6 → 4.0.7

package/skills/vds-skill/vds-scripts/docs/v0-sunset-known-issues.md

@@ -0,0 +1,88 @@
+# v0 API Sunset — Known Issues
+
+Tracked issues to address before or during unified.py v0 API sunset.
+
+---
+
+## KI-V0-001: Mode-incorrect `api_key` gate in `unified.py:81`
+
+**Status**: ✅ RESOLVED — unified.py cluster removed (VAMI-012 Task #49)
+
+**Original file**: `memory_orchestrator/src/vds_memory_orchestrator/service/services/unified.py:81`
+
+**Original issue**:
+
+```python
+if not self.config.mem0.api_key and not is_test:
+    logger.warning("Mem0 API key not provided, Pro features will be limited")
+    self._mem0_client = None
+    return
+```
+
+This gate was written for cloud-only mode. It had no awareness of `MEM0_MODE`, `qdrant_host`, or
+any self-hosted configuration introduced by VAMI-012. In self-hosted mode an `api_key` is not
+required, so this gate would short-circuit `UnifiedVDSService.initialize()` and leave
+`self._mem0_client = None` on a valid self-hosted setup.
+
+**Why it was safe (historical)**:
+
+`api/unified.py` router was not registered in any `app.include_router()` call in `service/main.py`.
+Zero HTTP paths reached `UnifiedVDSService` at runtime. The gate was unreachable over the network.
+
+**Causal link**:
+
+The same unmounted router was the root cause of `test_cache_warming_simple` failures:
+`POST /api/v1/sessions` → targets `api/unified.py` → router unmounted → uvicorn drops TCP
+connection pre-response → `httpx.ReadError` (not a 404, because no handler is registered).
+
+**RESOLUTION**:
+
+Caller audit (Task #49) confirmed the unified.py cluster was entirely self-contained dead code:
+- All `UnifiedVDSService` callers were route handlers inside the unmounted `api/unified.py` router
+- `services/unified.py` contained only mock stub implementations
+- `models/unified.py` was exclusively used within the cluster
+- `DataModelTransformer` re-export (`utils/data_transformer.py`) was preserved — it is used by
+  active services (`ai_memory_service.py`, `memory_crud_service.py`)
+
+**Files removed** (Branch A — full cluster deletion):
+- `memory_orchestrator/src/vds_memory_orchestrator/service/services/unified.py`
+- `memory_orchestrator/src/vds_memory_orchestrator/service/api/unified.py`
+- `memory_orchestrator/src/vds_memory_orchestrator/service/models/unified.py`
+- `memory_orchestrator/tests/service/test_unified_service.py`
+- `memory_orchestrator/tests/service/test_unified_api.py`
+
+**Fix commit**: see git log — `refactor(memory): remove superseded unified.py router (KI-V0-001)`
+
+**Discovered**: 2026-04-17, VAMI-012 Task #39 (integrator verification)
+**Resolved**: 2026-04-17, VAMI-012 Task #49 (integrator)
+
+---
+
+## KI-V0-001 Follow-up: `test_cache_infrastructure_works` skip removal
+
+**Status**: ✅ RESOLVED — skip removed, test passes 5/5 consecutive runs (VAMI-012 Task #51)
+
+**Original skip reason** (commit `b84ed94`):
+> "POST /api/v1/sessions targets unmounted api/unified.py router — uvicorn drops TCP connection pre-response."
+
+This skip reason was **mechanically inaccurate** even when written:
+- The live uvicorn worker crash was on `ai_memory_api.py` routes (mounted), not `api/unified.py` (unmounted/dead)
+- After Task #49 deleted the unified.py cluster, the skip reason became doubly stale
+
+**Root cause of skip (actual)**:
+- `test_cache_infrastructure_works` called `POST /api/v1/sessions` then checked `/api/v1/health/full` via `api_client`
+- `api_client` uses ASGI transport + mock service injection — the sessions endpoint worked fine via mock
+- The trailing health check (`/api/v1/health/full`) lacked the `async_client` health-layer mocks, making it unreliable
+
+**Fix applied (Task #51)**:
+- Removed `@pytest.mark.skip` decorator from `test_cache_infrastructure_works`
+- Removed `POST /api/v1/sessions` call — session_id hardcoded to `"cache-test-session"` (session creation is orthogonal to cache warming behavior)
+- Removed trailing `GET /api/v1/health/full` assertion — Redis layer health is already verified by `test_semantic_cache_status` (uses `async_client` with proper health-layer mocks)
+- Scope of test 1 is now correctly bounded: create memory → search twice → assert response structure
+
+**Verification**:
+- 5/5 consecutive clean runs (`3 passed in ~11s` each)
+- Full regression: `648+ passed, 10 skipped (pre-existing only), 0 failed`
+
+**Discovered**: 2026-04-17, VAMI-012 Task #42 (risk audit)
+**Resolved**: 2026-04-17, VAMI-012 Task #51 (integrator)

package/skills/vds-skill/vds-scripts/docs/vi/TRANSLATION-BACKLOG.md

@@ -0,0 +1,72 @@
+<!-- diátaxis: reference -->
+<!-- lang: vi -->
+
+# Tồn đọng bản dịch tiếng Việt / Vietnamese Translation Backlog
+
+> Quy tắc spec: tài liệu tiếng Việt phải do con người dịch (không dùng dịch máy). Xem `.gpt-5.4/specs/who-project-documentation-enhancement/requirements.md` — Non-Functional Requirements.
+
+Cập nhật lần cuối: 2026-04-23 (đã điều chỉnh để phản ánh trạng thái thật sau khi 16 bản nháp LLM bị iCloud dọn dẹp)
+
+## Trạng thái hiện tại
+
+- Tổng tài liệu tiếng Anh dưới `docs/agents/`: 77
+- Tổng tài liệu tiếng Việt dưới `docs/vi/agents/`: ~58 tài liệu đã được con người dịch + 3 bản nháp chờ rà soát = **61 tài liệu**
+- Còn thiếu bản dịch tiếng Việt: **16 tài liệu** (liệt kê bên dưới)
+
+## Bản nháp hiện có (chờ rà soát bởi con người — 3 mục)
+
+Các bản nháp này mang chú thích `<!-- draft-translation: needs-human-review -->`. Người rà soát nên kiểm tra thuật ngữ kỹ thuật, loại bỏ cảm giác "dịch máy", và xóa banner sau khi duyệt.
+
+- [`docs/vi/agents/reference/multi-agent-orchestrator.md`](./agents/reference/multi-agent-orchestrator.md) — nguồn: `../agents/reference/multi-agent-orchestrator.md`
+- [`docs/vi/agents/how-to/orchestrator-workflows/research-spec-audit-workflow.md`](./agents/how-to/orchestrator-workflows/research-spec-audit-workflow.md) — nguồn: `../agents/how-to/orchestrator-workflows/research-spec-audit-workflow.md`
+- [`docs/vi/agents/how-to/orchestrator-workflows/confluence-bitbucket-sync-workflow.md`](./agents/how-to/orchestrator-workflows/confluence-bitbucket-sync-workflow.md) — nguồn: `../agents/how-to/orchestrator-workflows/confluence-bitbucket-sync-workflow.md`
+
+## Bản dịch còn thiếu (chờ người dịch — 16 mục)
+
+Cho mỗi tài liệu dưới đây, người dịch tạo file tiếng Việt tại đường dẫn song song dưới `docs/vi/`, theo quy ước tên-file bằng chữ-hyphen (giữ nguyên CLI strings, code blocks, URL).
+
+### `docs/agents/reference/` (12 mục)
+
+- `excel-orchestrator.md`
+- `google-sheets-orchestrator.md`
+- `hexagonal-orchestrator.md`
+- `intellij-orchestrator.md`
+- `links-orchestrator.md`
+- `lsp-orchestrator.md`
+- `markdown-orchestrator.md`
+- `openapi-orchestrator.md`
+- `public-interface-orchestrator.md` _(tên file có underscore — được xem xét đổi tên trong pass riêng)_
+- `schema-orchestrator.md`
+- `sonarqube-orchestrator.md`
+- `structure-orchestrator.md`
+
+### `docs/agents/how-to/orchestrator-workflows/` (4 mục)
+
+- `analytics-pipeline-workflow.md`
+- `code-quality-gate-workflow.md`
+- `document-delivery-workflow.md`
+- `memory-progress-workflow.md`
+
+## Quy trình dịch tài liệu (cho tài liệu mới)
+
+1. Đọc tài liệu tiếng Anh tại `docs/agents/...`.
+2. Tạo file song song tại đường dẫn tương ứng dưới `docs/vi/`.
+3. Giữ header `<!-- diátaxis: X -->`, thêm `<!-- lang: vi -->`.
+4. Dịch prose + headings + table cells; giữ nguyên CLI strings, code blocks, URL, tên biến môi trường.
+5. Cập nhật tài liệu này — chuyển mục từ "Bản dịch còn thiếu" xuống "Lịch sử hoàn tất" bên dưới.
+
+## Quy trình rà soát bản nháp (cho 3 mục hiện có)
+
+1. Mở file, xác nhận có `<!-- draft-translation: needs-human-review -->`.
+2. Đọc song song với nguồn tiếng Anh.
+3. Sửa phần dịch sượng, thuật ngữ chuyên ngành, tên lệnh CLI.
+4. Xóa dòng `<!-- draft-translation: needs-human-review -->` và khối banner cảnh báo (block `> ⚠️ ...`).
+5. Chuyển mục xuống "Lịch sử hoàn tất".
+
+## Lịch sử hoàn tất (rỗng — cập nhật khi người rà soát xác nhận)
+
+_(Chưa có mục nào — cập nhật khi một bản nháp được duyệt hoặc một tài liệu mới được dịch.)_
+
+## Sự cố đã biết (context)
+
+- Ngày 2026-04-23: một lần dịch máy tạo ra 16 bản nháp, nhưng tất cả bị iCloud Drive đánh dấu `.nosync` và bị commit dọn dẹp `4e2cd398 fix(repo): remove invalid symlinks` xóa. Quyết định: KHÔNG tái tạo tự động — tôn trọng quy tắc spec "human-translated".

package/skills/vds-skill/vds-scripts/docs/vi/agents/README.md

@@ -0,0 +1,41 @@
+<!-- diátaxis: how-to -->
+
+<!-- TODO: translate — Vietnamese translation pending -->
+
+# VDS Agent Docs
+
+WHO-owned documentation hub for agents working in the VDS monorepo.
+
+## Sections
+
+- [Tutorials](tutorials/index.md)
+- [How-to Guides](how-to/index.md)
+- [Reference](reference/index.md)
+- [Explanation](explanation/index.md)
+
+## Primary Runtime Sources
+
+- [WHO project baseline](../../../AGENTS.md)
+- [Monorepo baseline](../../../../AGENTS.md)
+- [Centralized audit spec](../../../../.gpt-5.4/specs/audit-orchestrator/tasks.md)
+- [Scripts workspace guide](../../README.md)
+- [Unified CLI reference](../../../vds_cli/README.md)
+- [Audit orchestrator guide](../../../audit_orchestrator/README.md)
+- [Skills catalog guide](../../../../WHO-project/vds-skills/README.md)
+- [Search tools reference](reference/search-tools.md)
+- [Skills reference](reference/skills-reference.md)
+
+## Current Alignment Note
+
+- `WHO-project` is the canonical ecosystem for both reusable skills and routed scripts.
+- Use `vds-scripts-skill` as the platform-routing skill for command-family selection and current scripts-capability discovery.
+- Use specialist skills for deep workflow/runbook guidance.
+- The current authoritative latest-only audit/spec baseline is under the root `.gpt-5.4/specs/audit-orchestrator/` triplet.
+- Agent-facing docs must distinguish clearly between merged runtime behavior that exists in code today and remaining implementation work that is still incomplete.
+- `workflow-projects` is now present in the merged runtime as the current parent command surface for multi-project orchestration.
+- The current parent command is intentionally thin and should be documented that way: it composes `parse-registry`, `prepare`, `state readiness`, `state completeness`, and child `workflow-project` rather than replacing child project execution semantics.
+- Phase 131 exposes two separate parent-stage parallelism lanes, both bounded and operator-visible: maximum-parallel project preparation and maximum-parallel project analysis. Docs should keep those separate instead of collapsing them into child `--max-concurrent` repo fan-out.
+- Parent manifest/progress-state artifacts in Phase 131 are derived orchestration artifacts for monitoring, recovery scoping, and operator visibility. They are not a replacement for authoritative Postgres-backed readiness, completeness, evidence state, or child terminal artifacts.
+- Parent/child recovery semantics must stay explicit in docs: parent orchestration scopes retry/resume at the project level, while child `workflow-project` remains responsible for repo-level dispatch, provider failover, aggregation, and Confluence upload behavior.
+- Current runtime caveat: `workflow-projects` is merged and usable for bounded production slices, targeted testing, and operator-visible orchestration, but broad all-project execution should still start from bounded slices and explicit concurrency settings rather than assuming unlimited fan-out.
+- Multi-project orchestration must keep per-project artifact isolation and explicit outer concurrency settings; do not document shell fan-out as the preferred path when `workflow-projects` is available.

package/skills/vds-skill/vds-scripts/docs/vi/agents/explanation/features-overview.md

@@ -0,0 +1,29 @@
+---
+diátaxis: explanation
+audience: both
+complexity: basic
+last_updated: 2026-04-30
+phase_ref: 180
+language: vi
+---
+
+# Tổng quan Tính năng
+
+Tổng quan 9 tính năng chính của VDS Ecosystem.
+
+| Tính năng | Mô tả | Lệnh chính |
+|-----------|-------|------------|
+| CLI Audit | Kiểm toán repository | `vds-cli audit` |
+| Worktree | Git worktree qua CLI | `vds-cli worktree` |
+| Docs | Quản lý tài liệu | `vds-cli docs` |
+| Skills | Đồng bộ skill | `vds-cli skills` |
+| Progress | Báo cáo tiến độ | `vds-cli progress` |
+| Scheduler | Lịch trình cron | `vds-cli schedule` |
+| Confluence | Đồng bộ Confluence | `vds-cli confluence` |
+| Bitbucket | Tìm kiếm Bitbucket | `vds-cli bitbucket` |
+| Report | Báo cáo hàng ngày | `vds-cli report` |
+
+## Xem thêm
+
+- Tiếng Anh: [features-overview.md](../../agents/explanation/features-overview.md)
+- [Hệ sinh thái WHO](../../explanation/who-ecosystem-introduction.md)

package/skills/vds-skill/vds-scripts/docs/vi/agents/explanation/index.md

@@ -0,0 +1,14 @@
+<!-- diátaxis: explanation -->
+
+<!-- TODO: translate — Vietnamese translation pending -->
+
+# Explanation
+
+Conceptual guides for the WHO-centered automation workspace.
+
+- [WHO project baseline](../../../AGENTS.md)
+- [Monorepo baseline](../../../../AGENTS.md)
+- [WHO ecosystem model](who-ecosystem-model.md)
+- [Runtime verification and gap reporting](runtime-verification-and-gap-reporting.md)
+- [Orchestrator architecture](../reference/orchestrator-architecture.md)
+- [Skills catalog guide](../../../../vds-skills/README.md)

package/skills/vds-skill/vds-scripts/docs/vi/agents/explanation/runtime-verification-and-gap-reporting.md

@@ -0,0 +1,129 @@
+<!-- diátaxis: explanation -->
+
+<!-- TODO: translate — Vietnamese translation pending -->
+
+# Runtime Verification and Gap Reporting (Phase 3)
+
+Phase 3 of the WHO ecosystem alignment introduces a strict separation between
+file/catalog alignment and live runtime verification. A skills/doc surface can
+be internally aligned yet still fail in practice because the required runtime,
+credentials, network path, or active skill-discovery surface is incomplete.
+
+This guide defines the operator-facing contract for verifying runtime state
+without claiming unsupported CLI surfaces.
+
+## Runtime-Discovery Contract
+
+Runtime verification should confirm the state of the environment actually used
+by operators or agents in practice. The contract is evidence-based and should
+prefer existing supported commands over hypothetical convenience flags.
+
+### Discovery mechanisms
+
+- **Environment inspection**: confirm required environment variables, config
+  roots, and credentials locations are present and point to the expected VDS
+  paths.
+- **Credential verification**: confirm auth material is usable with existing
+  doctor commands such as `vds-cli audit --json-only doctor credentials`.
+- **Provider/profile verification**: confirm the configured profile set is
+  resolvable and available with existing commands such as
+  `vds-cli audit --json-only doctor profile-availability ...`.
+- **Readiness verification**: confirm project or repo state is materially ready
+  with existing commands such as `vds-cli audit --json-only state readiness ...`.
+- **Checklist/source verification**: confirm checklist retrieval and related
+  source surfaces with `vds-cli audit query-checklist ...` when the issue involves
+  source-checklist reachability rather than repo/project readiness.
+
+### Verification levels
+
+- **L1: Connectivity** — can the operator environment reach the required
+  service or source surface?
+- **L2: Authentication** — do the configured credentials authenticate
+  successfully for the intended surface?
+- **L3: Functional** — can an existing supported command perform a real,
+  minimal operation such as resolving readiness, listing checklist rows, or
+  validating profile availability?
+- **L4: Operational suitability** — is the surface usable enough for the
+  intended workflow within the expected timeout and environment constraints?
+
+## Known Runtime Gaps
+
+When runtime availability does not match the documented or cataloged
+expectation, the gap should be recorded explicitly rather than hidden behind a
+generic failure summary.
+
+### Gap classes
+
+- **Connectivity gap** — network path, host resolution, firewall, or transport
+  failure prevents access.
+- **Authentication gap** — credentials are missing, invalid, expired, or lack
+  sufficient permissions.
+- **Functional gap** — the service is reachable but the required operation or
+  workflow surface still fails.
+- **Environment gap** — local profile/config/runtime setup does not match the
+  documented expectation.
+
+### Reporting shape
+
+Each verified gap should record:
+
+- **Runtime status**: `READY`, `DEGRADED`, or `UNAVAILABLE`
+- **Gap ID**: stable identifier such as `GAP-RT-001`
+- **Surface**: which runtime surface failed (credentials, profile availability,
+  readiness, checklist retrieval, active skill-discovery, etc.)
+- **Description**: what did not match the documented expectation
+- **Impact**: what workflows are blocked or degraded
+- **Evidence**: exact command output or observed runtime signal
+- **Remediation**: next action to resolve or narrow the gap
+- **Status**: `OPEN`, `IN_PROGRESS`, or `RESOLVED`
+
+## Supported Operator Verification Pattern
+
+Use only commands already documented and supported in the current repo surface.
+
+### Credentials
+
+```bash
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit --json-only doctor credentials --require-state-dsn
+```
+
+### Profile / provider availability
+
+```bash
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit --json-only doctor profile-availability --mode active
+```
+
+### Project or repo readiness
+
+```bash
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit --json-only state readiness --project <PROJECT_PAGE_ID>
+```
+
+### Checklist/source surface verification
+
+```bash
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit query-checklist --checklist-page 88722450 --summary-only
+```
+
+## What This Guide Does Not Assume
+
+This guide does **not** assume the existence of convenience commands such as
+`vds-cli doctor --runtime-only` or `vds-cli status --show-gaps` unless those
+surfaces are implemented and documented elsewhere in the maintained repo.
+
+If such convenience surfaces are introduced later, they should be documented as
+an additive follow-up rather than retroactively treated as if they already
+exist.
+
+## Relation To Phase 3 Tasks
+
+- **TSK-3.14 / TSK-3.15**: define the runtime-discovery contract and compare
+  documented expectations against the active runtime surface used in practice.
+- **TSK-3.16 / TSK-3.17 / TSK-3.18**: document fallback behavior, runtime-status,
+  and known runtime gaps separately from file/catalog alignment.
+- **TSK-3.20 / TSK-3.21 / TSK-3.22**: support deterministic validation and clear
+  classification of runtime/tooling failures.

package/skills/vds-skill/vds-scripts/docs/vi/agents/explanation/whats-new.md

@@ -0,0 +1,37 @@
+---
+diátaxis: explanation
+audience: human
+complexity: basic
+last_updated: 2026-04-30
+phase_ref: 180
+language: vi
+---
+
+# Có gì Mới
+
+Theo dõi các thay đổi gần đây và xác minh môi trường của bạn đang cập nhật.
+
+## 2026-04-30 — Tài liệu toàn diện (Phase 180)
+
+Tài liệu mới bao gồm 8 phần mục tiêu:
+- Giới thiệu, Bắt đầu nhanh, Yêu cầu hệ thống, Tài liệu Cấu hình
+- Tổng quan Tính năng, Hướng dẫn Tiến triển, Ma trận So sánh Orchestrator
+- Tài liệu Kiến trúc, Kiến trúc Hệ thống, Luồng Dữ liệu
+
+## 2026-04-29 — Telegram Bridge & Lint Hygiene
+
+- **Telegram Bridge**: Bot thông báo với hỗ trợ multi-runner
+- **Lint Hygiene**: Sửa Track-α cho Phase 220
+
+## Kiểm tra sức khỏe nhanh
+
+```bash
+vds-cli docs validate
+pytest --co -q | tail -1
+vds-cli docs freshness-report --days 30
+```
+
+## Xem thêm
+
+- Tiếng Anh: [whats-new.md](../../agents/explanation/whats-new.md)
+- [Hệ sinh thái WHO](../../explanation/who-ecosystem-introduction.md)

package/skills/vds-skill/vds-scripts/docs/vi/agents/explanation/who-ecosystem-introduction.md

@@ -0,0 +1,21 @@
+---
+diátaxis: explanation
+audience: both
+complexity: basic
+last_updated: 2026-04-30
+phase_ref: 180
+language: vi
+---
+
+# Giới thiệu Hệ sinh thái WHO
+
+WHO Ecosystem là nền tảng làm việc của VDS—script, skill, CLI và quy tắc tích hợp có thể mở rộng. Tài liệu này hướng dẫn bạn khám phá hệ sinh thái từ tổng quan đến 37 orchestrator có sẵn.
+
+## Tầm nhìn
+
+Xây dựng trợ lý AI thông minh cho nhiều tác nhân trong hệ thống VDS.
+
+## Xem thêm
+
+- Tiếng Anh: [who-ecosystem-introduction.md](../../agents/explanation/who-ecosystem-introduction.md)
+- [Hệ sinh thái WHO](../../explanation/who-ecosystem-introduction.md)

package/skills/vds-skill/vds-scripts/docs/vi/agents/explanation/who-ecosystem-model.md

@@ -0,0 +1,36 @@
+<!-- diátaxis: explanation -->
+
+<!-- TODO: translate — Vietnamese translation pending -->
+
+# WHO Ecosystem Model
+
+`WHO-project` is the canonical VDS ecosystem for both reusable skills and routed scripts.
+
+## Canonical ownership
+
+- Skills live under `WHO-project/vds-skills/skills/`
+- Scripts and orchestrators live under `WHO-project/vds-scripts/`
+- `.agent/skills/` is a compatibility mirror or symlink path, not an authoring source
+- generated `AGENTS.md` surfaces are downstream outputs, not canonical content roots
+
+## Platform versus specialist guidance
+
+Use `vds-scripts-skill` as the **platform-routing skill** when you need to:
+- find the correct command family
+- understand the current WHO scripts workspace surface
+- route a task to the correct specialist skill
+
+Use specialist skills when you need deep workflow guidance, for example:
+- `audit-orchestrator-skill` for audit workflow execution and readiness/gating flows
+- `llm-analysis-skill` for LLM-backed content evaluation
+- `spec-creation-skill` for spec creation and consolidation
+- `lsp-skill` for LSP setup and usage
+- `circular-dependency-skill` for dependency-cycle analysis
+
+## Current scripts capability layers
+
+- routed command surfaces via `vds-cli`
+- standalone workspace capabilities such as markdown, hexagonal, MCP, and multi-agent support
+- shared support layers such as `vds_cli_common`
+
+This model keeps the platform skill concise while still covering the full current WHO ecosystem through references and routing aids.

package/skills/vds-skill/vds-scripts/docs/vi/agents/how-to/02-using-vds-ai-memory.md

@@ -0,0 +1,100 @@
+<!-- diátaxis: how-to -->
+
+<!-- TODO: translate — Vietnamese translation pending -->
+
+# How To Use VDS AI Memory
+
+Use the skill entrypoint first:
+
+- Skill: `WHO-project/vds-skills/skills/vds-ai-memory-skill/SKILL.md`
+
+Operational context:
+
+- [WHO project baseline](../../../AGENTS.md)
+- Skills catalog: `WHO-project/vds-skills/README.md`
+
+## Prerequisites
+
+Start the active VDS AI Memory runtime before using the CLI:
+
+```bash
+cd WHO-project/vds-scripts/memory_orchestrator
+docker compose --profile dev --profile mem0 up -d
+```
+
+This starts the active memory runtime stack from `memory_orchestrator/`.
+
+> `WHO-project/vds-ai-memory/` is historical/archive-only and should not be used for current startup or runtime guidance.
+
+## Base URL Resolution
+
+`vds-cli memory` (and direct `vds-memory`) load `~/.vds/.env` and resolve the
+API base URL in this order:
+
+1. `VDS_MEMORY_API_URL`
+2. `http://localhost:${API_PORT}` (when `API_PORT` is set)
+3. `http://localhost:8000`
+
+In most sessions, you should not need to pass `--api-url` manually.
+
+## CLI Commands (Recommended)
+
+The `vds-cli memory` subcommand is the primary interface for agents and interactive use.
+
+```bash
+# Search memories by semantic query
+vds-cli memory search "auth patterns" --limit 5
+
+# Store a new memory
+vds-cli memory store "PAR billing uses Spring Boot 3.2" \
+  --category code --importance high --tags spring-boot,PAR
+
+# Retrieve a specific memory by ID
+vds-cli memory get <memory_id>
+
+# List active sessions
+vds-cli memory sessions
+
+# Health check
+vds-cli memory health
+
+# Statistics (machine-readable)
+vds-cli memory --json-only stats
+```
+
+## Command Discovery
+
+- Use `vds-cli memory ...` for normal routed execution.
+- Put global options before the subcommand, for example: `vds-cli memory --json-only stats`
+- Use the direct package entrypoint for full command help:
+
+```bash
+./scripts/worktree_uv.sh run --project memory_orchestrator vds-memory --help
+```
+
+## Practical Rules
+
+- Capture durable decisions with dates, paths, commands, and evidence.
+- Prefer short decision records over long narrative summaries.
+- Use tags to improve searchability across agents.
+- Do not store secrets, tokens, or personal data.
+
+## Hook Integration (automatic, since Phase 6 HX.2)
+
+VDS AI Memory is wired into Claude Code via two parallel hook paths, both registered in `.claude/settings.local.json`:
+
+1. **Command path** (fallback, works even when Docker is down) — uses the `vds-cli memory-*` console scripts installed in `WHO-project/vds-scripts/.venv/bin/`:
+   - `vds-cli memory-session-context` on `SessionStart` (5s timeout) — pre-loads prior decisions
+   - `vds-cli memory-persist-stop` on `Stop` (30s) — auto-persists session summary
+   - `vds-cli memory-persist-stop --session-end` on `SessionEnd` (30s) — final summary
+   - `vds-cli memory-prompt-search` on `UserPromptSubmit` (3s) — per-prompt memory search
+
+2. **HTTP path** (low-latency, ~20× faster when Docker is up) — calls dedicated endpoints on the running memory service:
+   - `POST <BASE_URL>/api/v1/hooks/session-context` on `SessionStart`
+   - `POST <BASE_URL>/api/v1/hooks/session-persist` on `Stop`
+
+`<BASE_URL>` follows the same resolution order in **Base URL Resolution** above.
+
+Both paths run in parallel on the same events as a **dual-path safety net**. HTTP non-2xx responses are non-blocking in Claude Code, so if the memory service is unreachable (rebuilding, stopped, laptop offline), the command path still succeeds. You generally shouldn't need to do anything manually — just use `vds-cli memory store` for explicit saves and the hooks handle the rest.
+
+Env-var toggles: `VDS_HOOK_SESSION_MEMORY=0` disables SessionStart pre-load, `VDS_HOOK_MEMORY_PERSIST=0` disables Stop auto-persist, `VDS_HOOK_MEMORY_DECISIONS=0` disables decision auto-capture. Default all on.