npm - @mndrk/agx - Versions diffs - 2.0.26 → 2.0.32 - Mend

@mndrk/agx 2.0.26 → 2.0.32

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (831) hide show

package/cloud-runtime/standalone/docs/project-agent-migration-status.md DELETED Viewed

@@ -1,229 +0,0 @@
-# Project-Agent Migration Status
-Last reviewed: March 6, 2026
-## Summary
-The project-first migration is implemented at the schema/runtime level and partially complete at the terminology cleanup layer.
-- Schema foundation is in place.
-- Project-scoped APIs mostly exist.
-- Chat runtime loads project resources.
-- Runtime participant loading is DB-only.
-- Execution provenance/resolution is wired into the chat runtime.
-- Legacy compatibility names still exist in a few internal APIs/types.
-## Current Status
-### Implemented
-#### Schema
-- `agents` includes `voice`, `seed`, `model`, `provider`, and `color`.
-- `project_agents` exists.
-- `project_skills` exists.
-- `project_variables` exists.
-- `project_memory` exists.
-- `project_threads` exists.
-Key files:
-- [db/sqlite/001_agx_board_schema.sql](/Users/mendrika/Projects/Agents/agx-cloud/db/sqlite/001_agx_board_schema.sql:299)
-- [lib/sqlite-query-adapter.ts](/Users/mendrika/Projects/Agents/agx-cloud/lib/sqlite-query-adapter.ts:103)
-#### Project-scoped APIs
-- Project agent CRUD exists.
-- Project skill CRUD exists.
-- Project variable CRUD exists.
-- Project memory CRUD exists.
-- Project thread linking CRUD exists.
-Key files:
-- [app/api/projects/[id]/agents/route.ts](/Users/mendrika/Projects/Agents/agx-cloud/app/api/projects/[id]/agents/route.ts:14)
-- [app/api/projects/[id]/skills/route.ts](/Users/mendrika/Projects/Agents/agx-cloud/app/api/projects/[id]/skills/route.ts:8)
-- [app/api/projects/[id]/variables/route.ts](/Users/mendrika/Projects/Agents/agx-cloud/app/api/projects/[id]/variables/route.ts:8)
-- [app/api/projects/[id]/memory/route.ts](/Users/mendrika/Projects/Agents/agx-cloud/app/api/projects/[id]/memory/route.ts:8)
-- [app/api/projects/[id]/threads/route.ts](/Users/mendrika/Projects/Agents/agx-cloud/app/api/projects/[id]/threads/route.ts:9)
-#### Chat path integration
-- Chat route resolves active project context.
-- Project skills, variables, and memory are loaded for the active project.
-- These resources are injected into the stream context.
-- Per-agent execution provenance is built and passed into the stream runtime.
-- The stream runtime now resolves execution variables from project context and executes merged skill/memory context with provenance-aware logging.
-Key files:
-- [app/api/chat/route.ts](/Users/mendrika/Projects/Agents/agx-cloud/app/api/chat/route.ts:310)
-- [lib/stream-multiplexer.ts](/Users/mendrika/Projects/Agents/agx-cloud/lib/stream-multiplexer.ts:328)
-- [lib/agent-participants.ts](/Users/mendrika/Projects/Agents/agx-cloud/lib/agent-participants.ts:1)
-#### Compatibility layer
-- `useTeams` is now a compatibility shim over project APIs.
-- Most top-level project loading and project-agent loading flows exist.
-Key files:
-- [hooks/useTeams.ts](/Users/mendrika/Projects/Agents/agx-cloud/hooks/useTeams.ts:1)
-- [hooks/useProjects.ts](/Users/mendrika/Projects/Agents/agx-cloud/hooks/useProjects.ts:143)
-- [hooks/useProjectAgents.ts](/Users/mendrika/Projects/Agents/agx-cloud/hooks/useProjectAgents.ts:1)
-- [hooks/useProjectResources.ts](/Users/mendrika/Projects/Agents/agx-cloud/hooks/useProjectResources.ts:1)
-### Partially Implemented
-#### Workspace/team to project migration
-- There is a dedicated migration for legacy `teams`, `team_agents`, and `team_workspaces`.
-- It creates or matches projects, links `team_agents` into `project_agents`, and links legacy workspace threads into `project_threads`.
-- The migration is idempotent and has been run successfully against the local database.
-- The implemented behavior matches by normalized name/default project rather than using richer repo/task heuristics.
-Key files:
-- [lib/workspaces-to-projects-migration.ts](/Users/mendrika/Projects/Agents/agx-cloud/lib/workspaces-to-projects-migration.ts:1)
-- [app/api/migrate/workspaces-to-projects/route.ts](/Users/mendrika/Projects/Agents/agx-cloud/app/api/migrate/workspaces-to-projects/route.ts:1)
-- [scripts/migrate-workspaces-to-projects.ts](/Users/mendrika/Projects/Agents/agx-cloud/scripts/migrate-workspaces-to-projects.ts:1)
-#### Participants API consolidation
-- `/api/participants` is DB-backed.
-- Summarize and task extraction routes are DB-backed.
-- Chat participant loading is DB-backed.
-- Legacy participant fields are still present in some UI request payloads, but they are no longer used as canonical runtime state.
-Key file:
-- [app/api/participants/route.ts](/Users/mendrika/Projects/Agents/agx-cloud/app/api/participants/route.ts:17)
-#### UI and terminology migration
-- Core UI operates with project-backed data.
-- Agent creation/edit flows now use project assignment rather than team membership.
-- Composer mention plumbing has been renamed to project-group semantics.
-- Project/thread relationships are now exposed through `thread_ids`, with `workspace_ids` retained only as a temporary compatibility alias.
-Key files:
-- [components/chat-ui/ParticipantBar.tsx](/Users/mendrika/Projects/Agents/agx-cloud/components/chat-ui/ParticipantBar.tsx:165)
-- [components/thread/WorkspaceSidebar.tsx](/Users/mendrika/Projects/Agents/agx-cloud/components/thread/WorkspaceSidebar.tsx:791)
-- [components/chat-ui/ChatContainer.tsx](/Users/mendrika/Projects/Agents/agx-cloud/components/chat-ui/ChatContainer.tsx:1)
-- [app/agents/page.tsx](/Users/mendrika/Projects/Agents/agx-cloud/app/agents/page.tsx:1)
-- [components/chat-ui/Composer.tsx](/Users/mendrika/Projects/Agents/agx-cloud/components/chat-ui/Composer.tsx:1)
-- [hooks/useMentionAutocomplete.ts](/Users/mendrika/Projects/Agents/agx-cloud/hooks/useMentionAutocomplete.ts:1)
-### Not Implemented or Divergent From Target Spec
-#### `agents.config` still exists
-The target state called for dropping the unused `config` JSON column. It is still in the schema.
-Key file:
-- [db/sqlite/001_agx_board_schema.sql](/Users/mendrika/Projects/Agents/agx-cloud/db/sqlite/001_agx_board_schema.sql:303)
-#### Threads are not scoped via `threads.project_id`
-The target spec called for `threads.project_id`. The implementation uses `project_threads` as a join table instead.
-Key file:
-- [db/sqlite/001_agx_board_schema.sql](/Users/mendrika/Projects/Agents/agx-cloud/db/sqlite/001_agx_board_schema.sql:347)
-#### Resolution and provenance engine
-- `buildExecutionProvenance` is now used by the chat route.
-- Provenance is passed into the stream runtime per agent.
-- Runtime logs include resolved skill, variable, and memory provenance.
-Remaining gap:
-- There is still no first-class DB model for agent-scoped skills; the system currently supports project-scoped resources cleanly and agent-scoped memory via `agent_memory`, but agent-scoped skills are not yet backed by a dedicated canonical table.
-Key files:
-- [lib/db.ts](/Users/mendrika/Projects/Agents/agx-cloud/lib/db.ts:2543)
-- [lib/db.ts](/Users/mendrika/Projects/Agents/agx-cloud/lib/db.ts:2611)
-- [app/api/chat/route.ts](/Users/mendrika/Projects/Agents/agx-cloud/app/api/chat/route.ts:348)
-#### Legacy compatibility still exists
-- Runtime SQLite migration still checks for legacy team tables.
-- History store still has fallback behavior for legacy team workspace mapping.
-- `useTeams` still exists as a compatibility shim.
-- Bundle import/export still accepts legacy `teams` payloads while emitting `projects`.
-Key files:
-- [lib/sqlite-query-adapter.ts](/Users/mendrika/Projects/Agents/agx-cloud/lib/sqlite-query-adapter.ts:174)
-- [lib/history-store.ts](/Users/mendrika/Projects/Agents/agx-cloud/lib/history-store.ts:557)
-- [hooks/useTeams.ts](/Users/mendrika/Projects/Agents/agx-cloud/hooks/useTeams.ts:1)
-## Next Steps
-### 1. Decide whether to keep `project_threads` or align to `threads.project_id`
-- If current join-table semantics are acceptable, update the target spec.
-- If not, migrate to `threads.project_id` and remove `project_threads`.
-Primary files:
-- [db/sqlite/001_agx_board_schema.sql](/Users/mendrika/Projects/Agents/agx-cloud/db/sqlite/001_agx_board_schema.sql:347)
-- [app/api/projects/[id]/threads/route.ts](/Users/mendrika/Projects/Agents/agx-cloud/app/api/projects/[id]/threads/route.ts:9)
-- [app/api/threads/route.ts](/Users/mendrika/Projects/Agents/agx-cloud/app/api/threads/route.ts:1)
-### 2. Finish agent-scoped resource modeling
-- Add a canonical store for agent-scoped skills if dual-scope skills remain a requirement.
-- Decide whether agent-scoped variables should be disallowed entirely in the UI and types.
-- Decide whether `Participant` should be narrowed to identity-only fields plus project selection state.
-Primary files:
-- [lib/db.ts](/Users/mendrika/Projects/Agents/agx-cloud/lib/db.ts:2611)
-- [app/api/chat/route.ts](/Users/mendrika/Projects/Agents/agx-cloud/app/api/chat/route.ts:389)
-- [lib/stream-multiplexer.ts](/Users/mendrika/Projects/Agents/agx-cloud/lib/stream-multiplexer.ts:1)
-### 3. Remove remaining legacy compatibility aliases
-- Remove `workspace_ids` once all callers use `thread_ids`.
-- Remove `teamId` request aliases once no UI/API caller emits them.
-- Remove `useTeams` after remaining compatibility callers are migrated.
-Primary files:
-- [hooks/useProjects.ts](/Users/mendrika/Projects/Agents/agx-cloud/hooks/useProjects.ts:1)
-- [app/api/participants/route.ts](/Users/mendrika/Projects/Agents/agx-cloud/app/api/participants/route.ts:1)
-- [hooks/useTeams.ts](/Users/mendrika/Projects/Agents/agx-cloud/hooks/useTeams.ts:1)
-### 4. Remove legacy team fallback after migration validation
-- Validate migrated data in real environments.
-- Remove fallback reads against legacy team tables.
-- Drop team tables and any remaining runtime dependency on them.
-Primary files:
-- [lib/sqlite-query-adapter.ts](/Users/mendrika/Projects/Agents/agx-cloud/lib/sqlite-query-adapter.ts:174)
-- [app/api/migrate/teams-to-projects/route.ts](/Users/mendrika/Projects/Agents/agx-cloud/app/api/migrate/teams-to-projects/route.ts:17)
-### 5. Clean up schema drift
-- Drop `agents.config` if truly unused.
-- Remove any other legacy columns or aliases that are only present for migration compatibility.
-Primary files:
-- [db/sqlite/001_agx_board_schema.sql](/Users/mendrika/Projects/Agents/agx-cloud/db/sqlite/001_agx_board_schema.sql:303)
-- [migrations/sqlite_schema.sql](/Users/mendrika/Projects/Agents/agx-cloud/migrations/sqlite_schema.sql:309)
-## Recommended Execution Order
-1. Decide thread scoping model and align schema/API.
-2. Finish canonical agent-scoped resource modeling.
-3. Remove remaining compatibility aliases (`workspace_ids`, `teamId`, `useTeams`).
-4. Remove legacy team fallbacks and drop old tables.
-5. Clean up schema leftovers.

package/cloud-runtime/standalone/docs/runbook-shadow-read.md DELETED Viewed

@@ -1,66 +0,0 @@
-# Shadow-Read Validation Phase Runbook
-## Purpose
-Validate Postgres read correctness against SQLite before full cutover. Writes are served from Postgres; reads hit both PG and SQLite, and results are diffed. The phase runs for 48–72 hours on staging.
-## Go / No-Go Criteria
-**Zero-mismatch is the go/no-go threshold.** All three conditions must hold for the entire phase duration:
-| Metric | Threshold | Source |
-|--------|-----------|--------|
-| Shadow-read mismatch rate | **0%** (exact) | Diff engine comparing PG vs SQLite response bodies |
-| p99 endpoint latency | **≤ 500 ms** | Server-side request timing (shadow-read endpoints only) |
-| Lock-timeout rate | **≤ 0.5%** of total DB operations | Postgres `lock_timeout` error counter |
-Config file: `config/shadow-read.yaml`
-## Automatic Rollback Triggers
-Rollback is **trigger-based, not judgment-based**. If any threshold is breached within a rolling 5-minute evaluation window (after the minimum sample size of 100 requests is reached), the system must:
-1. **Disable shadow reads** — stop dual-reading from SQLite.
-2. **Revert read path to SQLite** — restore pre-migration read behavior.
-3. **Alert on-call** via configured alerting channel.
-4. **Log the breach event** with timestamp, metric name, observed value, and threshold.
-No manual approval is required to trigger rollback. The rollback fires automatically.
-## Hard Abort Thresholds
-### 1. Mismatch rate > 0%
-Any single mismatch between PG and SQLite responses is a hard abort. The diff compares JSON-normalized response bodies (ignoring field ordering and timestamp precision below seconds).
-**Action:** Immediate rollback. Investigate the divergent rows before re-attempting.
-### 2. p99 latency > 500 ms
-Sustained p99 above 500 ms over a 5-minute window indicates unacceptable performance regression from dual reads.
-**Action:** Immediate rollback. Profile query plans and connection pool usage.
-### 3. Lock-timeout rate > 0.5%
-Lock contention above 0.5% suggests the dual-read pattern is causing resource pressure on Postgres.
-**Action:** Immediate rollback. Review transaction isolation levels and query concurrency.
-## Procedure
-1. **Before starting:** Record baseline p99 latency and lock-timeout rate from production. Update `p99_latency_max_ms` in config if baseline differs significantly from 500 ms.
-2. **Enable shadow reads** on staging for endpoints listed in `config/shadow-read.yaml`.
-3. **Monitor dashboards** — metrics should be exported to the observability stack.
-4. **At 48 hours:** Review metrics. If all green, continue to 72 hours.
-5. **At 72 hours:** If zero mismatches and all metrics within thresholds → **GO** for cutover.
-6. **If any threshold breached at any point:** Automatic rollback fires. Phase is **NO-GO** until root cause is resolved and phase is restarted from zero.
-## Rollback Verification
-After automatic rollback fires, verify:
-- [ ] Shadow reads are disabled (no dual queries in logs)
-- [ ] Read path is serving from SQLite only
-- [ ] Alert was delivered to on-call
-- [ ] Breach event is logged with full context

package/cloud-runtime/standalone/docs/runbook.md DELETED Viewed

@@ -1,155 +0,0 @@
-# PG → SQLite Migration Runbook
-## Overview
-One-shot streaming migration from Postgres to SQLite. PG is **read-only** throughout — never modified or dropped by the migration script.
-## Prerequisites
-- Node.js 20+
-- Access to the PG database (read-only is sufficient)
-- Enough disk space for the SQLite file (~1.5x PG data size)
-- Application can be briefly paused (daemon + web)
-## Migration Window Strategy
-**Recommended: Brief write-pause.** Total downtime is typically under 5 minutes for databases under 1M rows.
-```
-Timeline:
-  T+0   Announce maintenance window
-  T+1   Pause writes (stop daemon + app)
-  T+2   Run migration script
-  T+3   Verify output (automatic)
-  T+4   Switch to SQLite backend
-  T+5   Resume app, confirm healthy
-  T+10  Monitor for 24h, keep PG as fallback
-```
-## Step-by-Step Procedure
-### 1. Pre-Migration (before the window)
-```bash
-# Dry run — validates PG connectivity, surveys tables, no writes
-npx tsx scripts/migrate.ts --dry-run
-# Review output: table count, row counts, estimated scope
-```
-- Confirm dry run completes without errors
-- Note total row count for time estimation
-- Ensure SQLite output path has sufficient disk space
-### 2. Pause Writes
-Stop all application components that write to Postgres:
-```bash
-# Stop the daemon/worker
-# (exact command depends on deployment — e.g., docker compose stop worker)
-# Stop the web application
-# (e.g., docker compose stop web)
-```
-Verify no active connections are writing:
-```sql
--- On PG: check for active non-idle connections
-SELECT pid, state, query_start, query
-FROM pg_stat_activity
-WHERE datname = 'agx' AND state != 'idle';
-```
-### 3. Run Migration
-```bash
-npx tsx scripts/migrate.ts \
-  --pg "postgresql://agx:PASSWORD@host:5432/agx" \
-  --sqlite agx-migrated.db \
-  --batch-size 1000 \
-  --schema agx
-```
-The script will:
-1. Stream all tables in FK-dependency order
-2. Run 4 verification checks (row counts, checksums, FK integrity, JSON validity)
-3. Exit 0 on success, exit 1 on failure
-### 4. Verify Output
-Verification is automatic. Confirm all checks pass:
-- **Row counts**: PG count == SQLite count per table
-- **Checksums**: Deterministic hash match per table
-- **FK integrity**: `PRAGMA foreign_key_check` returns no violations
-- **JSON validity**: `json_valid()` passes for all JSON columns
-If any check fails: see [Rollback](#6-rollback).
-### 5. Switch to SQLite
-```bash
-# Move the migrated database to the expected path
-mv agx-migrated.db /path/to/production/agx.db
-# Update environment
-export DB_BACKEND=sqlite
-# Restart the application
-# (e.g., docker compose up -d)
-```
-Smoke-test the running application:
-- Create a test task
-- List projects
-- Check dashboard loads
-### 6. Rollback
-**PG is never modified.** Rollback is straightforward:
-```bash
-# 1. Stop the app (if running on SQLite)
-# 2. Delete the SQLite file
-rm agx-migrated.db agx-migrated.db-wal agx-migrated.db-shm
-# 3. Revert to PG backend
-export DB_BACKEND=postgres
-# (or remove DB_BACKEND from .env)
-# 4. Restart the application
-```
-No data loss occurs — PG contains the authoritative data until you explicitly decommission it.
-### 7. Post-Migration Monitoring
-After switching to SQLite:
-- Monitor application logs for 24 hours
-- Verify write operations work (task creation, updates, deletions)
-- Check WAL file size stays reasonable
-- Keep PG running and accessible as a fallback
-### Point of No Return
-PG can be decommissioned **only after**:
-1. SQLite has been running in production for at least 7 days
-2. All application features verified working
-3. A backup of the SQLite database exists
-4. Team consensus that PG is no longer needed
-Until these criteria are met, PG remains the rollback target. **Do not drop PG tables or delete the PG database.**
-## Troubleshooting
-| Symptom | Action |
-|---------|--------|
-| Migration script hangs | Check PG connectivity; try smaller `--batch-size` |
-| Checksum mismatch | Likely a type coercion issue; check `sqlite_writer.ts` coercion logic for the affected table's column types |
-| FK violations | Table dependency order may be wrong; check `pg_streamer.ts` FK detection |
-| JSON validity failures | Check if PG contains malformed JSON; inspect with `SELECT col FROM table WHERE col::text !~ '^[{\[]'` |
-| Partial migration (crash) | Delete SQLite file and re-run — the script always starts fresh |

package/cloud-runtime/standalone/docs/specs/cli-postgres-removal.md DELETED Viewed

@@ -1,69 +0,0 @@
-# Spec: Remove Postgres/pg-boss/Docker from AGX CLI
-## Context
-The `agx-cloud` repository has successfully migrated to a SQLite-only architecture, removing the dependency on PostgreSQL and `pg-boss`. The CLI repository (`~/Projects/Agents/agx`) however, still relies on a local Dockerized Postgres instance and `pg-boss` for its job queue and graph execution runtime.
-To align the CLI with v2 architecture and simplify the local development experience (removing the Docker requirement), we must port the SQLite queue implementation to the CLI.
-## Goal
-Remove all traces of Postgres, `pg-boss`, and Docker from the CLI codebase. The daemon must function identically using `better-sqlite3` and the `SQLiteQueueAdapter`.
-## Scope
-### 1. Dependencies
-- **Remove:** `pg`, `pg-boss`
-- **Add:** `better-sqlite3`, `uuid` (if not present)
-### 2. Code Porting
-- **Source:** `agx-cloud`
-- **Destination:** `agx` CLI repo
-**Files to copy:**
-- `lib/queue/adapter.ts` -> `src/queue/adapter.ts` (Interface definitions)
-- `lib/queue/sqlite-adapter.ts` -> `src/queue/sqlite-adapter.ts` (Implementation)
-### 3. Refactoring
-#### A. Queue Wrapper (`src/lib/queue.js` or similar)
-Currently, the CLI likely has a wrapper around `pg-boss`.
-- **Action:** Replace the `pg-boss` instantiation with `SQLiteQueueAdapter`.
-- **Interface:** Ensure `send`, `work`, `start`, `stop` methods map correctly.
-- **Config:** Remove `DATABASE_URL` and `PG_BOSS_*` env vars. Use `AGX_DATA_DIR` or `~/.agx/queue.db` for the SQLite file.
-#### B. Graph Runtime (`src/graph/runtime.ts`)
-The graph execution engine uses the queue to schedule node execution (`agx.graph.tick`).
-- **Action:** Update import paths to use the new `QueueAdapter`.
-- **Logic:** The `SQLiteQueueAdapter` supports the same `send/work` pattern, so business logic changes should be minimal.
-- **Verification:** Ensure conditional logic (fork/join) works. The fixture `conditional-then-join-all.json` relies on the queue to handle state transitions reliably.
-#### C. Daemon Bootstrap (`lib/cli/daemon.js`)
-The daemon startup currently checks for Docker and Postgres availability.
-- **Remove:**
-    - `ensureDockerRunning()`
-    - `ensurePostgresReady()`
-    - `startPostgresContainer()`
-    - Health checks for port 5432
-- **Add:**
-    - `ensureSQLiteReady()`: Verify `better-sqlite3` can open the DB file and run `PRAGMA` checks (WAL mode, foreign keys).
-- **Simplify:** The daemon process no longer needs to manage a child Docker process. It just opens the DB file.
-### 4. Graph Execution & Daemon Compatibility
-The daemon is the "single writer" / coordinator in this architecture.
-- **Concurrency:** Ensure `SQLiteQueueAdapter` handles the "claim" pattern correctly (`UPDATE ... WHERE status='pending' LIMIT 1`) to support potential future multi-process workers (though v2 is currently single-coordinator).
-- **Persistence:** The graph state in the CLI is also stored in Postgres. This data layer MUST also be migrated to SQLite.
-    - **Action:** Port the `Task`, `Run`, `Node` tables to SQLite DDL.
-    - **Migration:** If existing user data is important, write a one-time `pg-to-sqlite` export script. If not (dev tool cache), a fresh start is acceptable for v2.
-## Verification Plan
-1.  **Unit Tests:** Run existing graph execution tests with the new adapter.
-2.  **Daemon Smoke Test:**
-    - `agx daemon start` (should not ask for Docker).
-    - `agx run "echo hello"` (should execute via queue).
-3.  **Complex Flow:**
-    - Run `conditional-then-join-all` fixture.
-    - Verify branching logic works: `cond` node should evaluate and enqueue *only* the correct branch.
-    - Verify `join` node waits for predecessors.
-## Rollback Strategy
-Keep `pg-boss` code in a `legacy/` directory or git branch until the SQLite implementation is stable in the CLI.

package/cloud-runtime/standalone/docs/specs/thread-mentions.md DELETED Viewed

@@ -1,53 +0,0 @@
-# Spec: Thread Mentions in Composer
-## Goal
-Allow users to reference other discussion threads within the composer using a specific trigger (`@#`), providing agents with context from those threads without cluttering the prompt with the full conversation history initially.
-## UX
-1.  **Trigger**: User types `@#`.
-2.  **Autocomplete**: A popover appears showing recent threads, filtered by title/ID.
-3.  **Selection**: User selects a thread. It is inserted into the composer as a "Thread Mention" pill (visual) or `@#<short-id>` text.
-4.  **Sending**:
-    -   When the message is sent, the client triggers an export of the referenced thread(s).
-    -   The thread is saved to a temporary markdown file on the server/host.
-    -   The agent receives a prompt that includes:
-        -   Thread Title
-        -   Summary (first 200 chars or custom summary)
-        -   File Path to the full transcript
-    -   The agent can choose to read the full file if the summary is insufficient.
-5.  **"Add to chat"**:
-    -   Root discussion threads (in the main chat view or thread sidebar) have an "Add to chat" button.
-    -   Clicking this button inserts the thread reference into the currently active composer (if any).
-## Technical Implementation
-### 1. Trigger Logic
--   **Hook**: `hooks/useThreadMention.ts`
--   **Trigger**: `@#` (at start of line or preceded by whitespace).
--   **Conflict Resolution**: `hooks/useMentionAutocomplete.ts` (which handles `@` for participants) must explicitly ignore `@#` to prevent overlapping popovers.
-### 2. Export Logic
--   **Module**: `lib/thread-export.ts`
--   **Constraint**: Max 100,000 characters per export.
--   **Strategy**:
-    -   Include Thread Header (Title, Participants, Metadata).
-    -   Walk **backward** from the newest message to the oldest.
-    -   Accumulate messages until the character budget (100k - header) is exhausted.
-    -   If truncated, prepend a note: `... (X earlier messages omitted)`.
-    -   This ensures the most recent context is always preserved.
--   **Storage**: System temporary directory (`os.tmpdir()`).
-### 3. API
--   **Endpoint**: `POST /api/thread-export`
--   **Body**: Full thread object (or ID to fetch server-side, though current implementation accepts the thread object from client cache).
--   **Response**: `ThreadRef` ({ title, summary, filePath }).
-### 4. Components
--   **Composer**: Integrates `useThreadMention` and renders `ThreadMentionPopover`.
--   **ThreadView / MessageList**: Adds "Add to chat" action button to root message headers.
-## Implementation Notes
--   **`useMentionAutocomplete.ts`**: This hook was updated to return `null` if the token starts with `@#`. This ensures that typing `@#` does not trigger the participant autocomplete, allowing `useThreadMention` to take over.
--   **`ThreadRef`**: The reference object returned by the export API is stored in the Composer's state and appended to the final message sent to the agent.
--   **Tiptap Node**: A `threadMention` node is used to render the reference as a pill in the editor.

package/cloud-runtime/standalone/docs/ux/GlobalChatFlow.storyboard DELETED Viewed

@@ -1,23 +0,0 @@
-# Global Chat Flow Storyboard
-Implementation path: `/Users/mendrika/Projects/Agents/agx-cloud`
-## Scene 1: Launching assistant chat
-1. User clicks the chat icon in the top nav (or hits the shortcut). On desktop/tablet the panel slides in from the left and floats over the page with no dimmed/blurred backdrop.
-2. The header is minimal (`Assistant` + controls). Context chips/switcher/breadcrumb UI are intentionally omitted.
-3. If no messages exist, the thread renders a short assistant greeting (`Hello! How can I help?`). Composer focus is ready immediately for first input.
-## Scene 2: Active conversation + stream feedback
-1. User submits a prompt from the assistant-ui composer (`Enter` submits).
-2. The thread shows streamed assistant text and displays an inline `Assistant is typing` indicator while the run is active.
-3. When the stream completes, the typing indicator clears and the composer stays ready for the next message.
-## Scene 3: Dismiss + responsive behavior
-1. User closes with the close icon or `Esc`; panel exits and focus returns to the launcher.
-2. Desktop/tablet remain left-floating panels with a light visual style.
-3. Mobile keeps a bottom-sheet layout with a drag handle and pinned composer area.
-## Backend stream contract
-1. Composer submit sends AI SDK UI messages to `POST /api/chat`.
-2. The route resolves provider/model from user settings (with CLI config fallback) and builds a scoped AGX prompt.
-3. The route executes AGX/default provider CLI inline and streams incremental deltas into the `assistant-ui` thread.

package/cloud-runtime/standalone/docs/ux/assistant-chat-cli.md DELETED Viewed

@@ -1,32 +0,0 @@
-# Assistant Chat (CLI Routed)
-Implementation repository: `/Users/mendrika/Projects/Agents/agx-cloud`
-## Scope
-This UX implementation uses an AI assistant chat (not multi-user group chat) with:
-- `assistant-ui` for the panel thread/composer UI
-- AI SDK UI message streaming over `POST /api/chat`
-- AGX/default provider CLI execution inline in the API route
-## Runtime flow
-1. User submits from chat panel composer.
-2. `assistant-ui` transport posts UI messages to `/api/chat` with `scope` + `contextId`.
-3. Route resolves provider/model:
-- `agx.user_settings` default provider/model (preferred)
-- `~/.agx/config.json` default provider fallback
-- final fallback: `claude`
-4. Route runs CLI inline and streams output chunks directly to the thread.
-## Files
-- API route: `/Users/mendrika/Projects/Agents/agx-cloud/app/api/chat/route.ts`
-- CLI adapter: `/Users/mendrika/Projects/Agents/agx-cloud/lib/chat/cli-assistant.ts`
-- Runtime wrapper: `/Users/mendrika/Projects/Agents/agx-cloud/components/chat/panel/assistant/AssistantRuntimeLayer.tsx`
-- Thread UI: `/Users/mendrika/Projects/Agents/agx-cloud/components/chat/panel/assistant/AssistantThread.tsx`
-- Composer UI: `/Users/mendrika/Projects/Agents/agx-cloud/components/chat/panel/assistant/AssistantComposer.tsx`
-- Panel shell integration: `/Users/mendrika/Projects/Agents/agx-cloud/components/chat/panel/ChatPanelShell.tsx`
-## Notes
-- This route requires Node runtime and should not run on Edge.
-- CLI stderr is captured for errors and not streamed as assistant text.
-- The chat thread renders a runtime-native typing indicator (`ThreadPrimitive.If running`) while the CLI stream is in progress.
-- Deprecated source path from earlier planning: `/Users/mendrika/Projects/Agents/agx/frontend`.