Merge pull request #4531 from atomantic/cos/app-improve-portos-default-documentation-msyum9k0/agent-be4e4d18

docs: update and improve PortOS documentation

Author: atomantic

README.md

@@ -402,6 +402,7 @@ Full catalog (including design plans, ADRs, and research notes): [docs/README.md
 - [Architecture Overview](./docs/ARCHITECTURE.md) — System design, data flow, and service diagram
 - [API Reference](./docs/API.md) — REST endpoints, full route-domain index, and WebSocket events
 - [Companion App API](./docs/COMPANION_APP_API.md) — PortDeck native mobile client discovery and HTTP API contract
+- [Federated Media Providers](./docs/FEDERATED_MEDIA_PROVIDERS.md) — Authenticated, capacity-aware peer audio provider wire contract and setup
 - [Storage Classification Contract](./docs/STORAGE.md) — when data belongs in PostgreSQL vs the filesystem, plus the new-data-store checklist
 - [Backup & Restore](./docs/BACKUP.md) — filesystem snapshots + mandatory PostgreSQL dumps and how to restore them
 - [Port Allocation](./docs/PORTS.md) — Port conventions (5553-5561) and allocation guide
@@ -424,14 +425,17 @@ Full catalog (including design plans, ADRs, and research notes): [docs/README.md
 - [Voice Mode](./docs/features/voice.md) — local STT/TTS/LLM voice assistant setup
 - [Chief of Staff](./docs/features/chief-of-staff.md) — Autonomous agent orchestrator
 - [Operational Goals](./docs/GOALS_OPERATIONAL.md) — Runtime priorities the CoS reads when generating work
+- [Agent Context](./docs/features/agent-context.md) — Per-task execution context and history tracking
 - [Agent Skills](./docs/features/agent-skills.md) — Task-type-specific agent prompts
 - [Claude on Ollama](./docs/features/claude-ollama.md) — Run agent tasks on a local model
 - [CoS Agent Runner](./docs/features/cos-agent-runner.md) — Isolated agent process architecture
 - [CoS Enhancement](./docs/features/cos-enhancement.md) — Hybrid search, proactive execution, error recovery
+- [MTPLX](./docs/features/mtplx.md) — Multiplexed agent execution and terminal streaming
 - [Memory System](./docs/features/memory-system.md) — Semantic memory with vector search and importance decay
 - [Digital Twin](./docs/features/digital-twin.md) — Genome, chronotype, taste, and mortality-aware goals
 - [Identity System](./docs/features/identity-system.md) — Extended identity modeling (P1-P3)
 - [Soul System](./docs/features/soul-system.md) — Identity scaffold with behavioral testing
+- [Privacy Center](./docs/features/privacy-center.md) — Machine-local vault, data brokers, and organization change tracking
 - [Brain System](./docs/features/brain-system.md) — Offline-first second brain
 - [POST](./docs/features/post.md) — Daily cognitive training
 - [App Wizard](./docs/features/app-wizard.md) — App registration and scaffolding
@@ -442,6 +446,8 @@ Full catalog (including design plans, ADRs, and research notes): [docs/README.md
 - [JIRA Sprint Manager](./docs/features/jira-sprint-manager.md) — Autonomous JIRA triage and implementation
 - [Writers Room](./docs/features/writers-room.md) — Prose-to-media writing environment with explicit AI passes
 - [Sprite Export Contract](./docs/features/sprite-export-contract.md) — What a published sprite atlas guarantees a consuming game
+- [Video Text Encoders](./docs/features/video-text-encoders.md) — Dual-encoder memory and clip conditioning for video models
+- [Music Renderer Benchmarks](./docs/features/music-renderer-benchmarks.md) — Benchmarking profiles and listening test evidence for local renderers
 - [OpenClaw](./docs/features/openclaw-operator-chat.md) — In-app operator-agent chat
 - [Stacker News](./docs/features/stacker-news.md) — Territory management and content stewardship
 - [Messages Security Model](./docs/features/messages-security.md) — Prompt-injection boundary around untrusted message content

docs/README.md

@@ -36,7 +36,7 @@ App management: [app-wizard](./features/app-wizard.md) · [autofixer](./features
 
 Chief of Staff: [chief-of-staff](./features/chief-of-staff.md) · [cos-agent-runner](./features/cos-agent-runner.md) · [cos-enhancement](./features/cos-enhancement.md) · [agent-context](./features/agent-context.md) · [agent-skills](./features/agent-skills.md) · [memory-system](./features/memory-system.md) · [claude-ollama](./features/claude-ollama.md) · [mtplx](./features/mtplx.md) · [prompt-manager](./features/prompt-manager.md)
 
-Identity & self: [digital-twin](./features/digital-twin.md) · [identity-system](./features/identity-system.md) · [soul-system](./features/soul-system.md) · [post](./features/post.md) (insights design spike: [plans/2026-06-03](./plans/2026-06-03-cross-domain-insights-engine.md))
+Identity & self: [digital-twin](./features/digital-twin.md) · [identity-system](./features/identity-system.md) · [soul-system](./features/soul-system.md) · [privacy-center](./features/privacy-center.md) · [post](./features/post.md) (insights design spike: [plans/2026-06-03](./plans/2026-06-03-cross-domain-insights-engine.md))
 
 Knowledge: [brain-system](./features/brain-system.md) · [messages-security](./features/messages-security.md)
 

docs/features/privacy-center.md

@@ -0,0 +1,60 @@
+# Privacy Center
+
+The Privacy Center is the PII (Personally Identifiable Information) management subsystem of PortOS. While the Digital Twin models aesthetic tastes, writing style, chronotype, and goals for AI prompts, the Privacy Center handles Sensitive Identity Data and Personal Records that must be protected, machine-local, and explicitly isolated.
+
+> [!IMPORTANT]
+> **Privacy Boundary Contract**: Per ADR [privacy records machine-local](../decisions/2026-08-08-privacy-records-machine-local.md), records stored within the Privacy Center are strictly machine-local. They **NEVER** ride the federation layer, sync buckets, or peer-to-peer share networks, and are never included in LLM prompt contexts unless explicitly requested by the user.
+
+---
+
+## Subsystems
+
+### 1. Vault
+The **Vault** is an encrypted, machine-local key-value store for sensitive personal documents and numbers:
+- Government identification (Passport numbers, SSN / Tax ID, Driver's license)
+- Financial identity (Bank account references, tax entity IDs)
+- Emergency contacts & private physical addresses
+
+Data in the Vault is stored encrypted at rest (`server/lib/vaultCrypto.js`) using machine-derived key material and requires standard authentication when auth is enabled.
+
+### 2. Organizations
+The **Organizations** registry maintains a list of third-party companies, services, and institutions that hold your personal data (e.g. financial institutions, utility providers, subscription services, medical providers). Each entry tracks:
+- Account references and data categories held
+- Contact channels and privacy policy links
+- Data retention & deletion policies
+
+### 3. Changes Inventory
+When changing physical addresses, phone numbers, legal names, or primary emails, the **Changes** workflow provides a checklist and tracking matrix:
+- Inventory of organizations requiring update
+- Notification status per organization (pending, requested, confirmed)
+- Verification notes and dates updated
+
+### 4. Data Brokers
+The **Data Brokers** module tracks exposure on data brokers, people-search sites, and marketing list aggregators. It manages:
+- Opt-out & CCPA / GDPR deletion request tracking
+- Direct opt-out URL shortcuts and template letters
+- Status verification dates and follow-up reminders
+
+---
+
+## Security Model & Data Flow
+
+```mermaid
+flowchart TD
+    User["User Interface (Settings / Privacy)"]
+    Vault["Vault Storage (data/vault.json)"]
+    Crypto["AES-256-GCM Encryption (vaultCrypto.js)"]
+    Orgs["Organizations & Changes (Postgres DB)"]
+    Federation["Federation & Peer Sync"]
+
+    User <-->|Local Read/Write| Crypto
+    Crypto <-->|Encrypted At Rest| Vault
+    User <-->|Local DB Access| Orgs
+    
+    Vault -.-x|BLOCKED| Federation
+    Orgs -.-x|BLOCKED| Federation
+```
+
+1. **Isolation**: No endpoint under `/api/privacy/*` or `/data/vault*` participates in peer sync or cloud-folder share buckets (`data/sharing/`).
+2. **Prompt Injection Safety**: Privacy Center records are omitted from default RAG indices (BM25 & pgvector) used by AI agents and Chief of Staff tasks.
+3. **Auditability**: All modifications to Vault entries produce localized JSON audit entries without logging raw payload values.

server/lib/federatedMediaWire.js

@@ -36,6 +36,14 @@ const styleByWords = new Map(FEDERATED_AUDIO_STYLES.map((value) => [words(value)
 const instrumentByWords = new Map(FEDERATED_AUDIO_INSTRUMENTS.map((value) => [words(value), value]));
 const AUDIO_PROMPT_RE = /^Instrumental ([a-z ]+) music with a ([a-z]+) mood, (slow|moderate|fast) tempo, (low|medium|high) energy(?:, featuring ([a-z ]+(?: and [a-z ]+){0,5}))?\. No vocals or spoken words\.$/;
 
+/**
+ * Render a validated audio profile into a canonical prompt string.
+ * Free-form text cannot cross the federation boundary (PII safety); consumers
+ * send validated enum profiles, which this function formats into deterministic prompt prose.
+ *
+ * @param {object} profile - Audio profile conforming to federatedMediaAudioProfileSchema.
+ * @returns {string|null} Canonical prompt string, or null if profile fails validation.
+ */
 export function renderFederatedMediaAudioPrompt(profile) {
   const parsed = federatedMediaAudioProfileSchema.safeParse(profile);
   if (!parsed.success) return null;
@@ -46,10 +54,15 @@ export function renderFederatedMediaAudioPrompt(profile) {
   return `Instrumental ${words(style)} music with a ${mood} mood, ${tempo} tempo, ${energy} energy${instrumentation}. No vocals or spoken words.`;
 }
 
-// Provider-side validation receives only the rendered text (not the local
-// profile) so older wire-v1 providers can still accept newer consumers. Parse
-// the canonical grammar back into fixed tokens and require an exact round trip;
-// arbitrary prose, names, lyrics, and redaction-sensitive fields fail closed.
+/**
+ * Validate that a prompt string conforms to the canonical federated audio grammar.
+ * Provider-side validation receives only the rendered text (not the local profile)
+ * so older wire-v1 providers can accept newer consumers. Parses the canonical grammar
+ * back into fixed tokens and requires an exact round trip.
+ *
+ * @param {any} value - Input string to test.
+ * @returns {boolean} True if input is a valid federated audio prompt string.
+ */
 export function isFederatedMediaAudioPrompt(value) {
   if (typeof value !== 'string') return false;
   const match = AUDIO_PROMPT_RE.exec(value);