armanisadeghi/ai-matrx

cloud-files

Use when modifying anything under features/files/, app/(a)/files/, app/(public)/share/, or any caller that uploads, downloads, lists, moves, renames, shares, or previews user files.

agent-copy

Add the canonical single icon-only copy/export control to any surface that shows data (rows, cards, lists, detail/record pages) using `components/agent-copy`: one CopyForAiIcon menu containing Copy, Copy JSON, Copy for AI, AI variants, downloads,…

cms-surfaces

Use when adding/changing a CMS surface manifest, the site_structure/html_pages_structure framing XML, a CMS context menu/extraSections wiring, or the cms-authoring platform skill. Also use when a new CMS route/tab needs an agent entry point.

embedded-image-studio

Use whenever a form needs to accept ONE image and produce permanent public URLs for one or more platform-specific sizes (OG image, social posts, avatars, logos, favicons, app icons). Replaces every legacy image-URL input, single-size uploader, and…

pattern-patrol

The Pattern Patrols system — recurring, certified sweeps that keep eradicated problem-patterns dead (dead ends, mobile breakage, light/dark violations, missing copy-for-AI, emojis, bare Loading text, unregistered coming-soon, type-suppression debt, and a…

core-route-headers

Bring any (core) route into conformance with the AppShell header + body-height + mobile doctrine — the repeatable fix recipe for the campaign to kill faux in-body headers, banned viewport-height calcs, avatar collisions, and mobile menus that vanish instead…

ios-mobile-first

Single source of truth for iOS-native mobile web UX. Covers viewport units, safe areas, Dialog-to-Drawer conversion, Tabs-to-vertical-stacking, touch targets, input zoom prevention, and responsive patterns. Use when building any UI component, fixing mobile…

supabase-realtime

The canonical doctrine for ALL Supabase realtime in matrx-frontend — postgres_changes, broadcast, and presence. Use BEFORE writing or modifying any `.channel(` subscription, any handler that reacts to a table this client also writes (echo suppression), any…

provider-access-scout

Produce decision-ready scouting records for user-connected OAuth, API, API-key, remote MCP, integration-marketplace, and partner-access campaigns. Use for assigned Provider Access Launch tasks when the easiest official route, minimum scopes, cost, account…

provider-access-submit

Execute a scouted third-party provider access campaign end to end under Arman's standing free/reversible setup authorization: account or app registration, exact scopes, reviewer assets, secure credential storage, receipt capture, canonical connection, real…

provider-access-chase

Monitor and advance pending third-party provider access campaigns by checking only due email threads, developer portals, support cases, and review deadlines; recording changes in Tasks and CRM; preparing the next response; and setting the next follow-up…

finalize-and-ship

The end-of-task routine — run every health check, fix what's broken, then commit and push. Use whenever you finish a unit of work and the user says to commit/push it, "ship it", "get it ready", "do this" (with no push instruction), or asks you to wrap up and…

tts-audio-system

Complete guide to the TTS (Text-to-Speech), STT (Speech-to-Text), and audio playback system. Covers Cartesia WebSocket streaming, Groq PlayAI REST TTS, Groq Whisper transcription, voice assistant hooks, and all speaker UI components. Use when working on audio…

live-ui-iteration

Work with Arman on an AI Matrx UI through a continuous localhost loop: implement his requested changes first, keep working autonomously through full surface completion and certification, verify desktop and mobile, and hand back only when the whole focused…

agent-execution-redux

State management architecture for the AI agent execution system AND the rules for triggering agent shortcuts from product code. Covers the four-layer Redux structure (agent source, app context, execution instances, request lifecycle), slice ownership, body…

data-to-kinds

The end-to-end pipeline that turns ANY structured data source — an API, a provider payload, a scraper/crawl result, a computed result, any aspect of our system — into registered platform kinds with @kind pydantic models, generated TypeScript types, canonical…

surface-check

Run THE full UI surface check on one surface — registration, values, write targets, inheritance/identity, invoked-agent parity and cost, the agent-self-context boundary, the canonical context menu, ProTextarea + text-stats decisions, header clearance, mobile,…

surface-write-targets

Make a surface AGENT-WRITABLE — declare writeTargets on its manifest, register page handlers, and verify a live agent run end-to-end. Use whenever a task says "let agents write/update/fill X on this page", "add write targets to <surface>", "make <surface>…

context-menu-v3

Wire the universal v3 right-click context menu (`EditableContextMenu` / `NonEditableContextMenu`) onto a surface, or fix a surface's wiring. Use whenever a task says "add a right-click menu to <surface>", "wire <surface> to the context menu", "the menu is…

agent-disclosure

Register the fixed AI jobs a surface already runs in the existing top Agents menu, and open each mandate in place. Use when a page, panel, overlay, or window already runs a mandate behind a button, assist, automatic action, or mode; when the agent-disclosure…

surface-authoring

Create, register, complete, or repair an AI Matrx agent-aware UI surface end to end: manifest identity, values, groups, inheritance, write targets, roles, DB mirror, live scope, canonical v3 context menus, Pro inputs, bindings, and verification. Use for new…

mandate-conversion

Convert an existing mandate to a real output contract (a registered kind, or honest text) WITHOUT losing a single field anyone downstream reads. The no-loss protocol — before/after payload capture, the consumer census, the kind-narrowing trap, batch…

create-agent

Create a hyper-specialized, production-grade AI Matrx platform agent through the hosted AI Dream MCP (agent_author / agent_catalog / agent_run), usually paired with a registered content-IR kind for its output. Use whenever anyone asks to create, build,…

consolidate

Take ONE registry node (Domain, Feature, or Sub-feature) and end its documentation sprawl: census every repo, extract everything that carries MEANING into the node's doc kit in common-docs, and DELETE it from the repos it came from — proven by a re-grep, not…

safe-cutover

Prove a cutover cannot break anything BEFORE it ships — enumerate every trigger path, close every gap, derive tests from live reality, stage on a branch, report a plain safe-or-not verdict. Use whenever replacing a live implementation with a canonical one:…

enhance-file-type

Add a new file type to the matrx-admin file system, or enhance any of the ~55 capability slots on an existing one (preview, edit, thumbnail, grid card, info, analysis, share, versions, control rail, action bar, conversion, diff, etc.). Use when adding support…

connect-matrx-extend

Wire matrx-frontend into the matrx-extend Chrome extension's bridge — adding or modifying a `FRONTEND_RPC` action handler, declaring a new window-panels deep-link entry point for the extension to trigger, exposing a new headless API route for the extension to…

context-assignment

Use whenever a task touches context selection, scope tagging, or the ctx system UI at matrx-frontend — adding a context picker to a surface, showing per-entity context status, tagging files/notes/agents to scopes, setting the working (active) context,…

handoff-cleanup

Dispatchable cleanup agent for handoff docs. Use when Arman says "/handoff-cleanup", "clean up the handoffs", "audit the handoffs", or asks whether handoff docs are stale or done. Sweeps docs/handoffs/ in BOTH repos (matrx-frontend + aidream), verifies every…

handoffs

The handoff-document system for docs/handoffs/*.md — how to write one, take one over, groom it every turn, and delete it. Use whenever you (1) end a large task with work remaining and need to hand off, (2) are told to continue / take over / pick up work from…

take

Arman passes ONE name (/take <name>) — a Domain, Feature, Sub-feature, Program, or Tail from the unassigned-handoffs register, or any registry node — and the agent does the rest: claims the row, gathers the node's whole truth, then builds under his standing…

rich-document-actions

Use whenever a task touches the RichDocument system at matrx-frontend — rendering markdown/interactive content WITH an action toolkit (copy, save to notes/scratch/task/code, save as file, HTML preview, copy HTML page, email, print, edit, open in full-screen…

agent-provision

Design the PROVISION for a call site — the exhaustive menu of values that place in the code can realistically produce, shaped so any candidate agent can be swapped in and actually do the job better. Covers the answerability test (can this question be answered…

agent-manifest

Build the MANIFEST for a mandate — the deliberate, measured decision about exactly what an agent must be given to answer its question, how that data is condensed to fit context, what it returns, and how the result is verified against ground truth. Use BEFORE…

agent-review-queue

Register anything you built that Arman must go see/test in the UI, read feedback, and route repair work by primary lane, required tools, ownership, and verification state. Use at the END of any task that produced something reviewable, at the START of a task…

type-safety

The canonical doctrine for fixing TypeScript type errors and writing type-safe boundary code. Generated types (database.types.ts, python-generated/api-types.ts) are the source of truth — code and data conform to them, never the reverse. Use when fixing type…

item-register

Create, contribute to, and run down an Item Register — the single self-contained tracking document for any effort with multiple agents' hands in it. Use when (1) Arman invokes /item-register <subject>, (2) a take or deep-dive reveals several sessions/agents…

shape-system

The canonical recipe for working with the Shape System — the platform-wide structured-content registry (content_ir.kind_definition + kind_surface / kind_component / kind_example). Use whenever a task involves adding or activating a kind ("add a kind", "new…

picker-custom-entry

Fix a closed-choice picker — a Select / Popover list / DropdownMenu built from data that offers a set of choices with no way for the person to add one. Use whenever you build or touch ANY control that offers choices (a tier / level / band / class / dimension…

build-sub-feature

Implement a sub-feature — a new capability added INTO a live, existing feature — to a world-class bar. Use whenever the user asks to add, extend, or wire a capability into something that already exists: 'add X to Y', 'extend Y to support X', 'build a new…