twinclaw 1.0.3 → 1.1.0

package/.env.example

@@ -0,0 +1,71 @@
+# ─── Runtime Core (REQUIRED) ────────────────────────────────────────────────
+# Master secret for HMAC webhook signature verification and secret-vault
+# encryption fallback. Must be set before startup.
+API_SECRET=your_api_secret_here
+
+# ─── Model Routing ───────────────────────────────────────────────────────────
+# At least one model API key must be present for AI functionality.
+
+# Primary model provider (Modal-hosted GLM-5-FP8).
+MODAL_API_KEY=your_modal_api_key_here
+
+# First fallback model provider (OpenRouter).
+OPENROUTER_API_KEY=your_openrouter_api_key_here
+
+# Second fallback model provider (Google Gemini).
+GEMINI_API_KEY=your_gemini_api_key_here
+
+# ─── Telegram Bot ────────────────────────────────────────────────────────────
+# Both keys required to enable Telegram messaging. Obtain token from @BotFather.
+TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
+
+# Your personal Telegram user ID (integer). Only this ID can interact with the bot.
+# Find it by messaging @userinfobot on Telegram.
+TELEGRAM_USER_ID=your telegram_user_id_here
+
+# ─── WhatsApp ────────────────────────────────────────────────────────────────
+# Phone number for the WhatsApp native client (E.164 format recommended).
+WHATSAPP_PHONE_NUMBER=your_whatsapp_number_here
+
+# ─── Groq (Speech-to-Text & Text-to-Speech) ─────────────────────────────────
+# Required when Telegram or WhatsApp voice messaging is active.
+# Free-tier API key from https://console.groq.com
+GROQ_API_KEY=your_groq_api_key_here
+
+# ─── Secret Vault (optional) ────────────────────────────────────────────────
+# Dedicated AES-256 encryption key for the secret vault.
+# Falls back to API_SECRET if unset.
+# SECRET_VAULT_MASTER_KEY=your_vault_master_key_here
+
+# Comma-separated list of additional secret names required at startup.
+# SECRET_VAULT_REQUIRED=DB_PASSWORD,SOME_TOKEN
+
+# ─── Control Plane API (optional) ───────────────────────────────────────────
+# HTTP port for the control plane API server (default: 3100).
+# API_PORT=3100
+
+# ─── Embedding (optional) ────────────────────────────────────────────────────
+# Embedding backend: "openai" (default) or "ollama" for local-only operation.
+# EMBEDDING_PROVIDER=openai
+
+# API key for OpenAI-compatible embedding endpoint (takes priority over OPENAI_API_KEY).
+# EMBEDDING_API_KEY=your_embedding_api_key_here
+
+# OpenAI API key used as fallback for embeddings when EMBEDDING_API_KEY is unset.
+# OPENAI_API_KEY=your_openai_api_key_here
+
+# Custom OpenAI-compatible embedding endpoint URL.
+# EMBEDDING_API_URL=https://api.openai.com/v1/embeddings
+
+# Embedding model name (default: text-embedding-3-small).
+# EMBEDDING_MODEL=text-embedding-3-small
+
+# Expected embedding vector dimensionality for sqlite-vec storage (default: 1536).
+# Must match your chosen embedding model.
+# MEMORY_EMBEDDING_DIM=1536
+
+# Base URL for a local Ollama server (default: http://localhost:11434).
+# OLLAMA_BASE_URL=http://localhost:11434
+
+# Ollama embedding model name (default: mxbai-embed-large).
+# OLLAMA_EMBEDDING_MODEL=mxbai-embed-large

package/.githooks/pre-commit

@@ -0,0 +1,5 @@
+#!/usr/bin/env sh
+set -eu
+
+echo "[TwinClaw] Running TypeScript check..."
+npm run check

package/.github/copilot-instructions.md

@@ -0,0 +1,170 @@
+# Agent Instructions — Full-Stack Web Development
+
+---
+
+## 1. The Prime Directive — Read Before You Write
+
+> **Before suggesting, generating, or modifying a single line of code, you MUST read and understand the existing implementation.**
+
+This is non-negotiable. Violating it produces broken, duplicate, or inconsistent code.
+
+**Concrete steps before any task:**
+
+1. **Discover the codebase structure** — read the top-level directory tree, then drill into the directories most relevant to the task.
+2. **Read every file that will be touched or that depends on what will be touched.** If unsure, read more, not less.
+3. **Trace the data flow end-to-end** — identify where data originates (API, DB, context, mock), how it is transformed, and where it is consumed.
+4. **Identify the established patterns** — naming conventions, service abstraction layers, state management approach, styling system, component structure. Match them exactly.
+5. **Fetch the relevant SKILL.md** — before implementing any non-trivial feature (UI, API, DB, auth, etc.), search for and read the most relevant skill file. This is required, not optional.
+
+Only after completing all five steps above should you write or suggest any code.
+
+---
+
+## 2. Architecture Principles
+
+### Service Abstraction — Absolute Rule
+- **All data access must go through the designated service layer** (e.g., `CmsService`, `ApiService`, or equivalent).
+- Direct `fetch('/api/...')` calls inside components or pages are **strictly forbidden**.
+- If you encounter a raw `fetch` in a component, refactor it into the service layer before proceeding.
+- The service layer is the single source of truth for data contracts between frontend and backend.
+
+### Modular Backend
+- Keep backend routers thin — they dispatch only.
+- Business logic lives in isolated handler modules (one concern per file).
+- Shared utilities (CORS, DB helpers, response formatting) go in a `shared.ts` or equivalent.
+- Never add logic to a router that belongs in a handler.
+
+### State Management
+- Global state (user session, app config, shared fetched data) lives in context or a dedicated store.
+- Local component state handles only ephemeral UI concerns.
+- Never duplicate global state inside local component state.
+
+### Environment Strategy
+- Development uses mocked/local data for fast iteration.
+- Production uses real APIs and databases.
+- Feature flags or env vars (`VITE_*`, etc.) control which path is active — never hardcode environment assumptions.
+
+---
+
+## 3. Database & Data Layer
+
+### Schema Conventions
+- Every table has: `id` (PK, auto or UUID), `created_at`, `updated_at`.
+- Soft deletes preferred: `status` column (`published` / `draft` / `archived`).
+- Scheduled content uses `scheduled_at` (ISO 8601).
+
+### Localization
+- Multi-lingual fields stored as JSON strings: `{"en": "...", "hi": "..."}`.
+- Always serialize with a helper before writing; always parse with a helper before returning to the frontend.
+- Frontend always receives typed DTO objects, never raw JSON strings.
+
+### Versioning & Safety
+- Every `PUT`/`PATCH` must fetch the existing row and save a version snapshot **before** applying changes.
+- Never perform destructive updates without a recoverable history.
+
+### Write Optimization
+- Avoid high-frequency DB writes. Apply throttling/debouncing for analytics events, rate history, and similar high-volume writes.
+- Debounce frontend-initiated writes via session tracking where possible.
+
+---
+
+## 4. Frontend — Design & Aesthetic Standards
+
+### Refer the frontend-design.md SKILL file for detailed design guidelines.
+### humanist-web-style.md represents our personal design language and should be loaded by default for all frontend work
+
+---
+
+## 5. Code Quality Standards
+
+### TypeScript
+- Strict mode always on.
+- No `any`. Use `unknown` and narrow, or define a proper type.
+- Interfaces for object shapes; types for unions and aliases.
+- Exported types live in a dedicated `types/` directory or co-located `*.types.ts` file.
+
+### Naming Conventions
+- **Files**: `kebab-case` for components and utilities. Match the project's existing convention exactly.
+- **Components**: `PascalCase`.
+- **Functions & variables**: `camelCase`.
+- **Constants**: `UPPER_SNAKE_CASE`.
+- **Types/Interfaces**: `PascalCase`, prefix interfaces with `I` only if the project already does so.
+
+### Error Handling
+- Every async operation has explicit error handling.
+- User-facing errors are friendly and actionable. Internal errors are logged with context.
+- Never swallow errors silently.
+
+### Comments & Documentation
+- Comments explain *why*, not *what*. Code explains what.
+- Complex algorithms and non-obvious decisions get a comment.
+- Public service methods get JSDoc.
+
+---
+
+## 6. API Design
+
+- RESTful by default. Follow existing route conventions precisely.
+- All responses use a consistent envelope: `{ data, error, meta }` or whatever the project already uses — match it.
+- Validate all inputs on the server side. Never trust client data.
+- Return appropriate HTTP status codes (200, 201, 400, 401, 403, 404, 409, 500).
+- CORS headers are set in a single shared location, never scattered across handlers.
+
+---
+
+## 7. Security
+
+- Never expose secrets, API keys, or credentials in frontend code.
+- Sanitize all user-generated content before storing or rendering.
+- Parameterize all database queries — no string interpolation into SQL.
+- Auth checks happen on the server, never rely solely on frontend guards.
+
+---
+
+## 8. Developer Workflow
+
+### Before Starting Any Task
+1. Read the task carefully. Identify ambiguities and resolve them before writing code.
+2. Read all relevant existing code (see Section 0).
+3. Fetch the relevant SKILL.md (see Section 1).
+4. Plan the implementation mentally. Identify files to create/modify.
+
+### Making Changes
+- Make the smallest change that correctly solves the problem. Don't refactor unrelated code while solving a bug.
+- If you discover a pre-existing bug or anti-pattern while working, flag it separately rather than silently changing unrelated behavior.
+- Run through the change mentally: does it break any existing data flow, type contract, or pattern?
+
+### Database Migrations
+- Every schema change gets a migration file. Never mutate the schema directly.
+- Apply locally first, verify, then apply to production.
+- Migration files are append-only — never edit a previously applied migration.
+
+### Deployment
+1. `npm run build` — verify zero errors and zero type errors.
+2. Run the local preview and manually verify the changed surfaces.
+3. Deploy via the project's established pipeline.
+
+---
+
+## 9. Prohibited Patterns
+
+These are hard rules. Finding one of these in existing code is a reason to refactor, not a reason to follow the pattern.
+
+- ❌ Raw `fetch` calls in components or pages — use the service layer.
+- ❌ `any` type in TypeScript.
+- ❌ Hardcoded environment-specific values (URLs, keys, flags) outside of env config.
+- ❌ Monolithic backend handlers — keep them modular and single-concern.
+- ❌ Destructive DB updates without versioning/snapshotting.
+- ❌ Placeholder UI with fake data shipped to production.
+- ❌ Inline styles for anything that belongs in the design system.
+- ❌ Logic duplication across the frontend and backend for the same validation rule.
+- ❌ Skipping the "read existing code" step because the task seems small.
+
+---
+
+## 10. When in Doubt
+
+- **Read more code.** The answer is almost always already in the codebase.
+- **Match the existing pattern**, even if you think a different approach is better. Flag the inconsistency separately.
+- **Ask before assuming** on anything that touches auth, payments, data deletion, or external API contracts.
+- **Fetch the SKILL.md.** It exists for a reason.

package/.github/skills/find-skills/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: find-skills
+description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
+---
+
+# Find Skills
+
+This skill helps you discover and install skills from the open agent skills ecosystem.
+
+## When to Use This Skill
+
+Use this skill when the user:
+
+- Asks "how do I do X" where X might be a common task with an existing skill
+- Says "find a skill for X" or "is there a skill for X"
+- Asks "can you do X" where X is a specialized capability
+- Expresses interest in extending agent capabilities
+- Wants to search for tools, templates, or workflows
+- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
+
+## What is the Skills CLI?
+
+The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
+
+**Key commands:**
+
+- `npx skills find [query]` - Search for skills interactively or by keyword
+- `npx skills add <package>` - Install a skill from GitHub or other sources
+- `npx skills check` - Check for skill updates
+- `npx skills update` - Update all installed skills
+
+**Browse skills at:** https://skills.sh/
+
+## How to Help Users Find Skills
+
+### Step 1: Understand What They Need
+
+When a user asks for help with something, identify:
+
+1. The domain (e.g., React, testing, design, deployment)
+2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
+3. Whether this is a common enough task that a skill likely exists
+
+### Step 2: Search for Skills
+
+Run the find command with a relevant query:
+
+```bash
+npx skills find [query]
+```
+
+For example:
+
+- User asks "how do I make my React app faster?" → `npx skills find react performance`
+- User asks "can you help me with PR reviews?" → `npx skills find pr review`
+- User asks "I need to create a changelog" → `npx skills find changelog`
+
+The command will return results like:
+
+```
+Install with npx skills add <owner/repo@skill>
+
+vercel-labs/agent-skills@vercel-react-best-practices
+└ https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 3: Present Options to the User
+
+When you find relevant skills, present them to the user with:
+
+1. The skill name and what it does
+2. The install command they can run
+3. A link to learn more at skills.sh
+
+Example response:
+
+```
+I found a skill that might help! The "vercel-react-best-practices" skill provides
+React and Next.js performance optimization guidelines from Vercel Engineering.
+
+To install it:
+npx skills add vercel-labs/agent-skills@vercel-react-best-practices
+
+Learn more: https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 4: Offer to Install
+
+If the user wants to proceed, you can install the skill for them:
+
+```bash
+npx skills add <owner/repo@skill> -g -y
+```
+
+The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
+
+## Common Skill Categories
+
+When searching, consider these common categories:
+
+| Category        | Example Queries                          |
+| --------------- | ---------------------------------------- |
+| Web Development | react, nextjs, typescript, css, tailwind |
+| Testing         | testing, jest, playwright, e2e           |
+| DevOps          | deploy, docker, kubernetes, ci-cd        |
+| Documentation   | docs, readme, changelog, api-docs        |
+| Code Quality    | review, lint, refactor, best-practices   |
+| Design          | ui, ux, design-system, accessibility     |
+| Productivity    | workflow, automation, git                |
+
+## Tips for Effective Searches
+
+1. **Use specific keywords**: "react testing" is better than just "testing"
+2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
+3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
+
+## When No Skills Are Found
+
+If no relevant skills exist:
+
+1. Acknowledge that no existing skill was found
+2. Offer to help with the task directly using your general capabilities
+3. Suggest the user could create their own skill with `npx skills init`
+
+Example:
+
+```
+I searched for skills related to "xyz" but didn't find any matches.
+I can still help you with this task directly! Would you like me to proceed?
+
+If this is something you do often, you could create your own skill:
+npx skills init my-xyz-skill
+```

package/.github/skills/frontend-design/LICENSE.txt

@@ -0,0 +1,177 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

package/.github/skills/frontend-design/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: frontend-design
+description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
+---
+
+This skill exists because AI-generated interfaces converge on a recognizable, low-density aesthetic ("The Vercel Clone"). Your job is to produce work that looks like a specific human made it for a specific reason.
+
+## Step 1 — The Context Derivator (Mental Sandbox)
+
+Do not write code until you answer these three questions. Be specific.
+
+**1. The "World" & Density:**
+Where does this live?
+- *High-Stress/Utility (e.g., Trading, Medical, Admin):* Needs **High Density**. Small type (12-14px / `text-xs` or `text-sm`), tight spacing, visible borders, information-first. Distinctiveness comes from *layout precision*, not decoration.
+- *Low-Stress/Expression (e.g., Portfolio, Marketing, Lifestyle):* Needs **Low Density**. Large type, generous whitespace, novel layouts. Distinctiveness comes from *typographic confidence*.
+
+**2. The Constraint:**
+Pick ONE constraint that shapes the design:
+- "Must work in direct sunlight" -> High contrast, no subtle grays.
+- "Used primarily via keyboard" -> Focus states are the primary aesthetic.
+- "Data-heavy dashboard" -> No "cards", use tables/lists only.
+- "Editorial focused" -> No images, typography carries the weight.
+
+**3. The "Signature" Interaction:**
+Define ONE non-standard interaction or visual element that defines this app:
+- *Example:* "A persistent sidebar that never scrolls."
+- *Example:* "Headings that are smaller than the body copy but bolder."
+- *Example:* "A monochrome palette where the only color is the cursor."
+- *Example:* "Grid lines are always visible."
+
+---
+
+## Step 2 — The One-Sentence Commit
+
+Summarize your direction in one sentence.
+*Example: "A utilitarian, high-density dashboard for data entry, using monospace fonts and visible grid lines, with no shadows or rounded corners."*
+
+---
+
+## Step 3 — Visual Execution Guidelines
+
+### Typography: Use Cultural Reasoning
+Avoid the "AI Default" stack: Inter, Roboto, Open Sans, Poppins, Space Grotesk. Do not just pick a category; reason about its **cultural association**:
+- **Utility & Engineering:** Use a high-quality Monospace (JetBrains Mono, IBM Plex Mono) to evoke documentation, code, and precision.
+- **Authority & History:** Use a transitional or high-contrast Serif (EB Garamond, Libre Baskerville) to evoke editorial, legacy, and trust.
+- **Modernity & Neutrality:** Use a grotesque (Unica77, Public Sans) but *track it tightly* (-0.02em) to evoke mid-century Swiss design.
+- **Warmth & Humanism:** Use a humanist sans (Gill Sans, Optima) to evoke friendliness without the "softness" of rounded fonts.
+
+### Color: Derive from a Core Material
+- **The Core Rule:** Do not use "primary" colors (pure blue, red, green). Use "Muddy" transitions or "Earth" tones (stone, clay, ink, paper).
+- **The Design Logic:** Pick **ONE** material color as your anchor (e.g., `#2D2926` for "Charcoal"). Derive the rest of the palette through relationships:
+    - *Surface:* Tint the background with 2-5% of your anchor color.
+    - *Borders:* Anchor color at 10-15% opacity.
+    - *Contrast:* Anchor color plus a deliberate shift in temperature (e.g., adding 5% blue or amber).
+- **Dark Mode:** Do not use `#000000` or `#121212`. Use a specific deep color derived from your anchor (e.g., deeply desaturated navy or forest green).
+
+### Layout: Fight the "Card" Mentality
+AI defaults to "Cards in a Grid." This is lazy.
+- **Try:** Visible grid lines separating content.
+- **Try:** List views instead of cards.
+- **Try:** Split-screen layouts (50/50).
+- **Try:** Sidebar navigation instead of top-bar.
+
+### Logic: "Does it need to be a card?"
+If the content is just text, it doesn't need a background color, a shadow, and a border radius. It just needs *space*.
+
+### Shadows & Radius
+- **Strict Consistency:** If you use `rounded-lg`, use it everywhere. If you use `rounded-none`, use it everywhere.
+- **Shadows:** Avoid the default distinct "drop shadow". Use subtle, large, diffuse shadows OR harsh, solid, 1px borders (brutalist).
+
+---
+
+## Step 4 — The "Anti-Slop" Checklist
+
+Before outputting code, verify:
+1.  **Density Check:** Is the text size 16px+ for a dashboard? -> **Fix it.** (Use 13-14px).
+2.  **Whitespace Check:** Am I using `py-24` just to fill space? -> **Fix it.**
+3.  **Color Check:** Is the primary color "Blurple" or "Teal"? -> **Change it.**
+4.  **Font Check:** Is it Inter or Space Grotesk? -> **Change it.**
+5.  **Effect Check:** Am I using Glassmorphism (backdrop-blur)? -> **Remove it.** (Unless explicitly requested).
+6.  **Animation Check:** distinct "staggered fade-in"? -> **Remove it.** (Make it instant or a single group fade).
+7.  **The Transplant Test:** Could this entire UI be transplanted onto a different product without it feeling generic? If it feels like "The Vercel UI," it **fails.**
+
+---
+
+## Implementation Standards
+
+- **React Architecture:** Functional components with TypeScript. Use semantic tags (`<header>`, `<main>`, etc.) within your JSX components.
+- **Tailwind Palette:** Use `tailwind.config.ts` for theme extensions. Define logic-based colors (e.g., `surface-primary`, `text-dimmed`) derived from your anchor color.
+- **Accessibility & Motion:**
+    - UI must support `prefers-reduced-motion` for all transitions.
+    - Interactive elements must satisfy a minimum **44x44px touch target**.
+    - Explicit focus states (`focus-visible`) are a requirement, not an afterthought.
+- **Performance:** For fonts, ensure `font-display: swap` is used. Use `next/font` or similar for optimized loading.