@mohammadhprp/system-prompt 0.12.1 → 0.12.3

package/framework/skills/laravel-best-practices/references/infer-conventions.md

@@ -0,0 +1,97 @@
+
+# Infer Conventions
+
+Learn how this application writes Laravel, then record what you learn as durable, path-scoped rules other agents will read. You are documenting reality, not improving it.
+
+## Ground Rules (read before you start)
+
+- Consistency first. The codebase's majority style is the convention. Never judge it, never propose a "better" pattern, never record what the code should do. If the app validates inline everywhere, that is the rule, even if Form Requests would be nicer.
+- Skip what an active tool produces, keep what a tool would fight. Inspect the project's Pint and Rector configuration first; a Rector transformation is tooling-owned only when its package and relevant rule or set are installed and enabled. Active tools may rewrite code toward one canonical form: `$casts` to `casts()`, `$fillable` to attributes, magic accessors to the `Attribute` class, pipe-string rules to arrays, `$signature` to `#[Signature]`, named migrations to anonymous, and many more. When the app already sits at an active tool's target form, the tool owns it, so record nothing. But when the app deliberately holds a form an active tool would refactor away, such as legacy `getXxxAttribute()` accessors the `Attribute` class would replace, no tool can reproduce that choice and an agent defaults the other way. That against-the-grain hold is exactly what to record.
+- Record decisions, not defaults. A consistent pattern earns a rule only when it reflects a choice: the app took one valid option where the framework or common practice offered others, or the pattern would surprise a competent agent. Framework defaults steer nothing, so skip them: anonymous migrations, `$signature` commands, `ShouldQueue` jobs, `casts()` on Laravel 11+, named routes, Rule objects in `app/Rules`, and `Mail::fake()` or `Bus::fake()` to isolate framework services. A real fork is not enough on its own. Weigh the side the app took, and record only the side an agent would not reach for by itself: inline closures everywhere, legacy accessors, a bespoke query layer. Watch for the false fork too. "No Mockery" next to facade fakes is not a choice against Mockery, because they double different things. The test for every candidate: without this rule, would the next agent plausibly write it differently? Only "yes" earns a rule.
+- Architecture choices are the gold. Record presence and deliberate absence. The structural pattern the app commits to is the highest-signal convention and the one no tool can decide: Action classes and how they are invoked (`handle` / `execute` / `__invoke`), service objects, dedicated query objects exposing `builder()`, DTOs (spatie/laravel-data vs readonly classes), Form Request validation vs inline, an events and listeners spine vs direct calls, and domain or module folders. Also record a consistent non-pattern, such as "query Eloquent directly in controllers, no repository layer", so the next agent matches the app's altitude instead of over-engineering.
+- Never duplicate `.ai/rules`. Read `.ai/rules/index.md` and the area files before the sweep. A dimension already covered there is marked done and skipped.
+- Evidence or silence. A convention needs at least 3 consistent examples and no meaningful rival to become a candidate. Every Step 1 verdict applies this bar.
+- The recorded rule states the convention, nothing else. One or two imperative lines: this project does X, so do X here. Keep detection evidence out. No counts, ratios, current usage, file lists, or example paths, because that is proof for the confirm step, not part of the rule. One short syntax fragment at most, and point to `search-docs` for API details.
+
+## Process
+
+Each step ends on a checkable completion criterion. Do not advance until it holds.
+
+Fan out when you can. The sweep is embarrassingly parallel. If your environment can spawn subagents (a Task, dispatch, or equivalent tool), do Step 0 yourself, then hand each checklist group (A to J) and the architecture map to its own subagent. Each subagent runs the greps, reads a few representative files, and returns structured verdicts (dimension, verdict, evidence, proposed glob / title / note). You aggregate, dedupe, then run Steps 3 to 5. It is far faster on a real app. No subagents available? Run the steps in sequence, with the same bar and the same output.
+
+### Step 0: Orient
+
+Read `composer.json` (installed packages tell you which checklist groups apply), the `pint.json` / PHPStan / Rector config, `.ai/rules/index.md` if present, and most important, map the `app/` tree. List every directory under `app/` (and any `Modules/`, `src/`, `packages/`, or domain root). Every folder beyond Laravel's default skeleton (`Http`, `Models`, `Providers`, `Console`, `Exceptions`) is a structural pattern the app committed to and a high-value rule waiting to be written: `Actions`, `Services`, `Data` or DTOs, `Queries`, `Repositories`, `ViewModels`, `Pipelines`, `Support`, `Enums`, `Contracts`, `Observers`, or `Domain` and module roots. Note each one. You will confirm how it is used in Step 2.
+
+This app ships a frontend stack, so the frontend checklist group applies. Sweep it.
+
+Done when: you have the applicable checklist groups, the dimensions already recorded in `.ai/rules`, and a list of every non-default `app/` directory mapped to the pattern it represents.
+
+### Step 1: Predefined sweep
+
+Open `references/checklist.md` and work every applicable dimension using its search hints. Give each exactly one verdict:
+
+- Pattern. Clears the bar, rival under ~20% of sites, and reflects a real choice (passes the decisions-not-defaults test). A recording candidate. Cite 2 to 3 example files.
+- Conflict. Both styles present in meaningful numbers. Report the split with counts and example files. Never record a preferred winner while the code remains mixed, even in yolo, because that would describe an aspiration rather than reality. Record only if the user identifies a stable path or context boundary that explains both styles; otherwise defer until the code is reconciled.
+- Default. Consistent, but a framework or common-practice default the agent already writes unprompted. Skip it as a no-op, not a convention.
+- No signal. Under the bar: feature unused, or too few examples. Skip silently (one summary line at most).
+- Tooling-owned or Already-recorded. Skip per the ground rules.
+
+Done when: every applicable dimension carries exactly one of those verdicts.
+
+### Step 2: Open-ended pass
+
+First, close out the architecture map from Step 0. For every non-default `app/` directory you listed, confirm how the pattern is used and apply the same evidence and decisions-not-defaults tests as Step 1. Generator-standard or sparsely used directories such as `Rules`, `Observers`, `Mail`, and `Notifications` are signals to inspect, not automatic conventions. Make genuine structural patterns candidates: Action classes invoked via `handle` / `execute` / `__invoke`, Services constructor-injected, `Queries` objects exposing `builder(): Builder`, DTOs as readonly classes or spatie/laravel-data, module or domain folders as the unit of organization. Scope each qualifying pattern to its own directory glob. Also record a consistent deliberate absence, such as "no repository layer, controllers query Eloquent directly", so the next agent matches the app's altitude.
+
+Then find what else makes this codebase itself: base or abstract classes most code extends, traits used everywhere, tenancy or authorization scoping woven through queries, naming schemes, and custom helpers. Same evidence bar, cite files. Record every genuine structural pattern, and cap the other house findings at ~5 so the pass stays high-signal.
+
+Done when: every non-default `app/` directory from Step 0 has a verdict, and the pass has produced its cited house findings (or concluded there are none).
+
+### Step 3: Confirm
+
+Present every candidate in one batch. Per item: dimension, verdict, evidence (counts and files), and the exact proposed `glob` or `globs` / `title` / `note`. Conflicts are presented as questions about an existing context boundary or deferred cleanup, not as a choice of future style.
+
+Default mode is confirm: record only what the user approves. Switch to yolo only when the invocation said so ("yolo", "don't ask", "just record them"), then record all pattern candidates without asking. Conflicts still go to the user in yolo.
+
+Done when: every candidate is approved, rejected, or (conflicts) decided.
+
+### Step 4: Record
+
+Make one `record-rule` call for each glob an approved convention applies to. Choose the most specific globs that cover the cited evidence from the mapping table below; if a convention spans models and migrations, record it under both domains so agents discover it from either path. The `note` is the bare convention: strip every trace of detection (see the ground rule). If `record-rule` is unavailable (rules disabled), report the full rule text so the user can enable `BOOST_RULES_ENABLED` or add it by hand.
+
+Record this:
+
+> Accessors and mutators: use the legacy magic-method style (`getXxxAttribute()` / `setXxxAttribute()`), not the `Attribute` class. Match it in models.
+
+Not this:
+
+> Accessors/mutators use the legacy magic-method style; the `Attribute`-class style is not used anywhere (13 legacy, 0 Attribute-class), e.g. `app/Models/Post.php`. Match the legacy style in existing models.
+
+Done when: every approved item has a successful tool response, and any failure is reported with its rule text.
+
+### Step 5: Summarize
+
+List recorded rules (file and title), conflicts the user deferred, notable no-signals, and remind the user to commit `.ai/rules` so their team and agents share the conventions.
+
+## Glob mapping
+
+Attach each rule to the most specific path that covers its evidence. Never a lazy `app/**` when a subtree fits. Match the glob to where the code actually lives, which is not the same in a default skeleton and in a modular or DDD layout. Use the Step 0 `app/` map to pick the real path.
+
+Examples:
+
+- Models: `app/Models/**` in a default app, or `app/Modules/Blog/Models/**` / `src/Domain/Blog/**` in a modular one.
+- Controllers, routing, validation, responses: `app/Http/**`, or `app/Modules/*/Http/**` when each module owns its HTTP layer.
+- Actions, Services, DTOs: `app/Actions/**`, `app/Services/**`, `app/Data/**`, or the module path the app actually uses.
+- Tests: `tests/**`.
+- Migrations and database: `database/migrations/**`.
+- Truly app-wide (rare, e.g. auth retrieval): `app/**`.
+
+`record-rule` takes one glob. When a convention genuinely spans two domains (e.g. UUID keys touch models and migrations), call it once per domain with the same title and note; mentioning another path in the note does not make the rule discoverable there.
+
+## Edge cases
+
+- Rules disabled or `record-rule` missing: detection is read-only, so Steps 0 to 3 still run, and recording falls back to the manual path in Step 4.
+- Tiny or fresh app: most dimensions land on no-signal. Say so honestly ("not enough code to infer conventions yet") and record nothing.
+- Huge app: each dimension is a bounded grep plus a handful of file reads. Sample representative files, do not read everything.
+- Re-runs: reading `.ai/rules` in Step 0 makes re-runs incremental, so only new or undecided dimensions surface.
+- Non-standard layout (modules, DDD): the open-ended pass catches the layout itself as convention #1. Adapt the globs in the mapping table to the observed paths.

package/framework/skills/laravel-best-practices/references/pest-testing.md

@@ -1,16 +1,8 @@
----
-name: pest-testing
-description: "Use this skill for Pest PHP testing in Laravel projects only. Trigger whenever any test is being written, edited, fixed, or refactored — including fixing tests that broke after a code change, adding assertions, converting PHPUnit to Pest, adding datasets, and TDD workflows. Always activate when the user asks how to write something in Pest, mentions test files or directories (tests/Feature, tests/Unit, tests/Browser), or needs browser testing, smoke testing multiple pages for JS errors, or architecture tests. Covers: test()/it()/expect() syntax, datasets, mocking, browser testing (visit/click/fill), smoke testing, arch(), Livewire component tests, RefreshDatabase, and all Pest 4 features. Do not use for factories, seeders, migrations, controllers, models, or non-test PHP code."
-license: MIT
-metadata:
-  author: laravel
----
-
-# Pest Testing 4
+# Pest Testing 5
 
 ## Documentation
 
-Use `search-docs` for detailed Pest 4 patterns and documentation.
+Use `search-docs` for detailed Pest 5 patterns and documentation.
 
 ## Basic Usage
 
@@ -46,6 +38,7 @@ it('is true', function () {
 - Run minimal tests with filter before finalizing: `php artisan test --compact --filter=testName`.
 - Run all tests: `php artisan test --compact`.
 - Run file: `php artisan test --compact tests/Feature/ExampleTest.php`.
+- Run only tests affected by recent changes (Tia): `./vendor/bin/pest --parallel --tia`.
 
 ## Assertions
 
@@ -82,16 +75,58 @@ it('has emails', function (string $email) {
 ]);
 ```
 
-## Pest 4 Features
+## Pest 5 Features
 
 | Feature | Purpose |
 |---------|---------|
+| Tia (Test Impact Analysis) | Rerun only tests affected by recent changes |
+| Time-Balanced Sharding | Split tests across CI shards by execution time |
+| New Validation Expectations | `toBeEmail()`, `toBeUlid()`, `toBeIpAddress()`, and more |
 | Browser Testing | Full integration tests in real browsers |
 | Smoke Testing | Validate multiple pages quickly |
 | Visual Regression | Compare screenshots for visual changes |
-| Test Sharding | Parallel CI runs |
 | Architecture Testing | Enforce code conventions |
 
+### Tia (Test Impact Analysis)
+
+Tia reruns only tests affected by recent changes and replays cached results for the rest, dramatically reducing suite duration:
+
+<!-- Tia Example -->
+```shell
+./vendor/bin/pest --parallel --tia
+```
+
+- Replayed tests are not skipped — cached tests store everything they produced, including covered lines and branches.
+- Detects Laravel, Symfony, Livewire, and Inertia automatically.
+
+### New Validation Expectations
+
+Pest 5 ships eight new validation matchers, all supporting `.not` negation:
+
+<!-- Pest 5 Validation Expectations -->
+```php
+expect('nuno@pestphp.com')->toBeEmail();
+expect('01ARZ3NDEKTSV4RRFFQ69G5FAV')->toBeUlid();
+expect('192.168.1.1')->toBeIpAddress();
+expect('00:1a:2b:3c:4d:5e')->toBeMacAddress();
+expect('example.com')->toBeHostname();
+expect('example.co.uk')->toBeDomain();
+expect('Zm9vYmFy')->toBeBase64();
+expect('deadbeef')->toBeHexadecimal();
+```
+
+### Time-Balanced Sharding
+
+Distribute tests across CI shards by execution time rather than count:
+
+<!-- Pest Sharding Example -->
+```shell
+./vendor/bin/pest --update-shards
+./vendor/bin/pest --shard=1/4
+```
+
+Commit `tests/.pest/shards.json` to the repository so CI shards stay consistent.
+
 ### Browser Test Example
 
 Browser tests run in real browsers for full integration testing:
@@ -140,14 +175,8 @@ $pages->assertNoJavaScriptErrors()->assertNoConsoleLogs();
 
 Capture and compare screenshots to detect visual changes.
 
-### Test Sharding
-
-Split tests across parallel processes for faster CI runs.
-
 ### Architecture Testing
 
-Pest 4 includes architecture testing (from Pest 3):
-
 <!-- Architecture Test Example -->
 ```php
 arch('controllers')

package/framework/skills/laravel-best-practices/references/security.md

@@ -90,7 +90,7 @@ Correct:
 
 ## CSRF Protection
 
-Include `@csrf` in all POST/PUT/DELETE Blade forms. In Inertia apps, the `@csrf` directive is automatically applied.
+Include `@csrf` in all POST/PUT/DELETE Blade forms. Inertia doesn't use `@csrf`; its HTTP client sends the `XSRF-TOKEN` cookie back as the `X-XSRF-TOKEN` header, which Laravel accepts in place of the `_token` field.
 
 Incorrect:
 ```blade

package/framework/skills/laravel-best-practices/references/style.md

@@ -44,7 +44,7 @@ Strings — use `Str` and fluent `Str::of()` over raw PHP:
 // Incorrect
 $slug = strtolower(str_replace(' ', '-', $title));
 $short = substr($text, 0, 100) . '...';
-$class = substr(strrchr('App\Models\User', '\'), 1);
+$class = substr(strrchr('App\Models\User', '\\'), 1);
 
 // Correct
 $slug = Str::slug($title);

package/framework/skills/laravel-best-practices/references/tailwindcss.md

@@ -1,4 +1,3 @@
-
 # Tailwind CSS Development
 
 ## Documentation

package/framework/styles/README.md

@@ -6,8 +6,11 @@ A curated catalog of design system references from [Refero Styles](https://style
 
 | Style | Description | Preview |
 | --- | --- | --- |
-| [Linear](./linear/README.md) | Midnight precision instrument — near-black surfaces, acid-lime accent, tight Inter typography. | ![Linear preview](https://images.refero.design/styles/refero.design/image/eee18c0c-a85f-4a66-83f6-f9f38d284825.jpg) |
-| [Raycast](./raycast/README.md) | Midnight command center, coral neon — almost-black canvas, warm coral brand accent, glass navigation. | ![Raycast preview](https://images.refero.design/styles/refero.design/image/ee40e139-0b24-47a0-9ea0-98372d317c5b.jpg) |
+| [Factory](./factory/README.md) | Terminal war room — stark black canvas, light figure-ground cards, and restrained orange/green data signals. | ![Factory preview](./factory/assets/preview.jpg) |
+| [Huly](./huly/README.md) | Midnight observatory — violet-to-coral aurora hero, dark productivity surfaces, and pill-shaped controls. | ![Huly preview](./huly/assets/preview.jpg) |
+| [Linear](./linear/README.md) | Midnight precision instrument — near-black surfaces, acid-lime accent, tight Inter typography. | ![Linear preview](./linear/assets/preview.jpg) |
+| [Notion](./notion/README.md) | Warm paper notebook — off-white canvas, editorial typography, blue primary action, and playful accent panels. | ![Notion preview](./notion/assets/preview.jpg) |
+| [Raycast](./raycast/README.md) | Midnight command center, coral neon — almost-black canvas, warm coral brand accent, glass navigation. | ![Raycast preview](./raycast/assets/preview.jpg) |
 
 ## How Styles Are Organized
 
@@ -15,7 +18,9 @@ Each style entry follows this structure:
 
 ```text
 styles/<style-name>/
-└── README.md       # Full design system reference: palette, typography, spacing, components, tokens
+├── README.md       # Concise style overview and implementation guidelines
+├── DESIGN.md       # Full design system reference: palette, typography, spacing, components, tokens
+└── assets/         # Preview images and other style assets, when provided
 ```
 
 ## How to Use a Style
@@ -32,4 +37,4 @@ All styles are sourced from [Refero Styles](https://styles.refero.design/) — a
 ## Related Repository Areas
 
 - [`skills/`](../skills/) contains task-specific procedures for AI coding agents.
-- [`references/standards/`](../references/standards/) contains canonical engineering rules.
+- [`references/standards/`](../references/standards/) contains canonical engineering rules.

package/framework/styles/factory/DESIGN.md

@@ -0,0 +1,360 @@
+# Factory — Style Reference
+> Terminal war room at midnight. Factory is a stark black control surface where a single white card lands like a flashlit dispatch — the only object in the room is the work itself.
+
+**Theme:** dark
+
+Factory operates as a terminal war room: deep black canvas, weight-400 Geist type pressed tight with negative tracking, and generous negative space that lets two functional accents — signal orange and metric green — speak above the noise. The signature move is the light card floating on near-black ground (#eeeeee panels on #101010 canvas), creating stark figure/ground contrast rather than soft elevation. Almost all interaction is carried by monochrome surfaces; chromatic color is reserved for live data states and status pulses, never decoration. Components sit flat with minimal radii, thin 1px borders, and zero shadow dependency — the design earns its depth through contrast and spacing rhythm, not blur or glow.
+
+## Tokens — Colors
+
+| Name | Value | Token | Role |
+|------|-------|-------|------|
+| Obsidian Canvas | `#101010` | `--color-obsidian-canvas` | Page background, footer base — the void everything else is measured against |
+| Carbon Lift | `#1d1a18` | `--color-carbon-lift` | Raised dark surfaces, nav wells, button fills — one step up from canvas for interactive depth |
+| Ash Stroke | `#3d3a39` | `--color-ash-stroke` | Hairline borders, ghost button outlines, separator lines |
+| Graphite Mid | `#4d4947` | `--color-graphite-mid` | Mid-tone fills for chart bodies, secondary surfaces, neutral data visualization |
+| Warm Granite | `#8a8380` | `--color-warm-granite` | Muted body text, secondary copy, inactive labels — warm gray to soften the black |
+| Pale Stone | `#b8b3b0` | `--color-pale-stone` | Tertiary text, section eyebrows, subdued supporting copy |
+| Bone | `#eeeeee` | `--color-bone` | Primary text, light card surfaces, the single bright figure on dark ground |
+| Chalk | `#fafafa` | `--color-chalk` | High-emphasis light button fill, log-in button, elevated neutral surface |
+| Signal Orange | `#ee6018` | `--color-signal-orange` | Orange decorative accent for icons, marks, and small graphic details |
+| Metric Green | `#a0ca92` | `--color-metric-green` | Green decorative accent for icons, marks, and small graphic details |
+
+## Tokens — Typography
+
+### Geist — All interface text — body, headings, buttons, nav, hero. Used at weight 400 almost universally; weight 500 is reserved for emphasis (e.g. footer heading). The flat 400-only treatment is a signature: authority is implied by size and tracking, not by bold weight. · `--font-geist`
+- **Substitute:** Inter, system-ui
+- **Weights:** 400, 500
+- **Sizes:** 12, 14, 16, 36, 44, 72
+- **Line height:** 1.0–1.5
+- **Letter spacing:** -0.0400em, -0.0310em, -0.0250em
+- **Role:** All interface text — body, headings, buttons, nav, hero. Used at weight 400 almost universally; weight 500 is reserved for emphasis (e.g. footer heading). The flat 400-only treatment is a signature: authority is implied by size and tracking, not by bold weight.
+
+### Geist Mono — Captions, labels, status tags, metric units — always uppercase 12px with tight tracking. Carries the 'terminal' voice that distinguishes engineering surfaces from marketing surfaces. · `--font-geist-mono`
+- **Substitute:** JetBrains Mono, IBM Plex Mono, ui-monospace
+- **Weights:** 400
+- **Sizes:** 12, 14, 16
+- **Line height:** 1.0–1.2
+- **Letter spacing:** -0.0200em
+- **Role:** Captions, labels, status tags, metric units — always uppercase 12px with tight tracking. Carries the 'terminal' voice that distinguishes engineering surfaces from marketing surfaces.
+
+### Type Scale
+
+| Role | Size | Line Height | Letter Spacing | Token |
+|------|------|-------------|----------------|-------|
+| caption | 12px | 1 | -0.24px | `--text-caption` |
+| body-sm | 14px | 1.43 | — | `--text-body-sm` |
+| body | 16px | 1.5 | — | `--text-body` |
+| heading | 36px | 1.1 | -1.12px | `--text-heading` |
+| heading-lg | 44px | 1.12 | -1.1px | `--text-heading-lg` |
+| display | 72px | 1 | -2.88px | `--text-display` |
+
+## Tokens — Spacing & Shapes
+
+**Base unit:** 8px
+
+**Density:** comfortable
+
+### Spacing Scale
+
+| Name | Value | Token |
+|------|-------|-------|
+| 8 | 8px | `--spacing-8` |
+| 16 | 16px | `--spacing-16` |
+| 24 | 24px | `--spacing-24` |
+| 32 | 32px | `--spacing-32` |
+| 40 | 40px | `--spacing-40` |
+| 56 | 56px | `--spacing-56` |
+| 80 | 80px | `--spacing-80` |
+| 96 | 96px | `--spacing-96` |
+| 120 | 120px | `--spacing-120` |
+
+### Border Radius
+
+| Element | Value |
+|---------|-------|
+| nav | 3px |
+| cards | 10px |
+| buttons | 3px |
+| largePanels | 20px |
+
+### Layout
+
+- **Page max-width:** 1200px
+- **Section gap:** 96px
+- **Card padding:** 24px
+- **Element gap:** 24px
+
+## Components
+
+### Top Navigation Bar
+**Role:** Persistent header across all pages
+
+Transparent over #101010 canvas. Height ~64px. Left-aligned wordmark 'FACTORY' in #eeeeee, 12px Geist Mono uppercase, letter-spacing wide. Nav links (Product, Enterprise, Pricing, News, Company, Careers) in #eeeeee at 14px Geist weight 400, uppercase. Log In = #fafafa fill, 3px radius, #101010 text, 0 14px padding. Contact Sales = ghost text link with arrow, transparent fill, 1px #3d3a39 border, 0px radius, 24px vertical padding.
+
+### Dark Filled Button
+**Role:** Primary interactive control in dark contexts
+
+Background #1f1d1c, text #eeeeee, 3px border-radius, 0 14px padding, Geist 14px weight 400. No border. Used for actions that commit within a dark surface.
+
+### Light Filled Button (Log In)
+**Role:** High-emphasis auth trigger
+
+Background #fafafa, text #eeeeee (note: on the light fill, text is inverted to dark in practice — #101010), 3px border-radius, 0 14px padding. The only chromatic-contrast button in the system; appears once in the nav.
+
+### Ghost Text Link
+**Role:** Secondary navigation, in-text links, 'Read More' affordances
+
+Transparent background, 1px #3d3a39 border, 0px radius (flat), 24px vertical padding, #eeeeee text. Behaves like a typographic button — no fill ever appears on hover, only text/border color shift to #fafafa.
+
+### Light Surface Card
+**Role:** Featured content panels, CTAs, case studies — the figure on dark ground
+
+Background #eeeeee, 10px border-radius, 24px padding all sides, no shadow. Contains dark text (#101010 or #060505) inside. Often carries a subtle grain/noise texture overlay. This is the system's primary way to create visual hierarchy on dark pages.
+
+### Dashboard Frame
+**Role:** Product hero — the live software factory preview
+
+macOS window chrome (traffic-light dots) on a #0d0d0d panel with 10px radius. Internal content is a dark grid of metric tiles with 1px #1d1a18 dividers. Header bar: dark fill, Geist Mono 12px uppercase for window title, status dot in #ee6018.
+
+### Metric Tile
+**Role:** Individual data cell inside the dashboard
+
+No background, 1px #1d1a18 hairline divider, 20px padding. Label: Geist Mono 12px uppercase #b8b3b0, tracking -0.24px. Value: Geist 36px weight 400, #eeeeee, tracking -1.12px. Sparkline below: 40px tall, 1px stroke in #ee6018 or #a0ca92.
+
+### CTA Section Card
+**Role:** Conversion closer at page bottom
+
+Light card (#eeeeee) ~480px wide, 10px radius, 24px padding, optional grain texture. Eyebrow: Geist Mono 12px uppercase, #ee6018 dot + #101010 text. Headline: Geist 36px weight 400, #101010. CTA: dark filled button using #101010 fill, #eeeeee text, 3px radius.
+
+### Status Pulse
+**Role:** Inline 'live' indicator on logos, avatars, section headers
+
+6px filled circle in #ee6018 with optional 1px stroke. Sits immediately before label text. No animation required, but pairs with marquee/animation in the marquee logo strip.
+
+### Logo Strip (Trust Bar)
+**Role:** Social proof band beneath hero
+
+Single row of partner wordmarks on #101010 canvas, all rendered in #8a8380 at consistent visual weight. No card backgrounds, no dividers — just the wordmarks floating in negative space. Separated from surrounding sections by 96px vertical breathing room.
+
+### Feature Card Row
+**Role:** Multi-card sections explaining product capabilities
+
+Dark cards (transparent on #101010) with 1px #1d1a18 hairline border, 10px radius, 20px padding. 'Read More →' ghost link in footer. No card background fill — the card is implied by the border, not the surface.
+
+### Footer
+**Role:** Site footer with link columns and brand mark
+
+Background #101010, 96px+ vertical padding. Headings: Geist Mono 12px uppercase #eeeeee. Links: 14px Geist weight 400 #8a8380. No dividers between columns — generous column gap (24–36px) does the separation.
+
+## Do's and Don'ts
+
+### Do
+- Keep the canvas #101010 on every section. Light cards (#eeeeee) are the only objects allowed to be bright.
+- Use Geist 400 for everything. Reach for weight 500 only when a label must dominate a dense surface (footer headings, key CTAs).
+- Apply negative letter-spacing proportionally to size: -0.04em at 72px, -0.025em at 44px, -0.02em at 12px. Display type earns its weight through tightness, not boldness.
+- Reserve #ee6018 for live status, build-state indicators, and accent strokes in data charts. Never use it as a button fill.
+- Set border-radius to 3px on buttons and nav elements, 10px on cards, 20px on the largest panels. Do not round corners more than this — the system is not soft.
+- Build depth through #eeeeee-on-#101010 contrast and 96px+ section gaps. Do not introduce drop shadows or blur to fake elevation.
+- Use Geist Mono 12px uppercase for eyebrows, status labels, and column headers. This is the system's secondary voice and the fastest way to signal 'instrument, not marketing'.
+
+### Don't
+- Do not introduce additional accent colors. The palette is two neutrals (#101010, #eeeeee), one warm gray for muted text (#8a8380), and two functional accents (#ee6018, #a0ca92). Anything else is noise.
+- Do not use weight 600+ or bold for headings. The system speaks at weight 400 with tight tracking — bolding breaks the voice.
+- Do not put #ee6018 or #a0ca92 on button backgrounds, card surfaces, or large text fills. They are data-voice colors, not chrome colors.
+- Do not use line-height above 1.5. Display sizes use lh=1; body sits at 1.5. Anything looser makes the page feel editorial rather than technical.
+- Do not add drop shadows, glows, or blurs to cards, buttons, or modals. The system's elevation is contrast, not depth-of-field.
+- Do not mix in serif typefaces or display fonts. Geist and Geist Mono only.
+- Do not fill buttons with brand color. The primary action is a neutral dark fill (#1f1d1c) or a neutral light fill (#fafafa) — chromatic CTAs would break the monochrome chrome.
+
+## Surfaces
+
+| Level | Name | Value | Purpose |
+|-------|------|-------|---------|
+| 0 | Obsidian Canvas | `#101010` | Page base, hero, all non-card sections |
+| 1 | Carbon Lift | `#1d1a18` | Nav well, inline buttons, subtle panel elevation |
+| 2 | Bone Card | `#eeeeee` | Light cards on dark ground — the signature figure/ground move |
+| 3 | Chalk Elevated | `#fafafa` | Light button fill, top of the light surface stack |
+
+## Elevation
+
+No shadows. Depth is built through figure/ground contrast — a #eeeeee card landing on a #101010 canvas does the work a drop shadow would do in other systems. The only box-shadow token observed is a 1px hairline at near-black, never a diffuse glow. This keeps the interface flat and instrument-like.
+
+## Imagery
+
+Imagery is minimal and product-led. The dominant visual is a photorealistic macOS dashboard screenshot serving as the hero — a real-feeling terminal panel with traffic-light chrome, monospaced column headers, and live sparklines in orange and green. There is no lifestyle photography, no people, no abstract gradients. Decorative texture on light cards is a subtle film-grain noise overlay, not an illustration. Logos in the trust bar are rendered as monochrome wordmarks, not as color photos. The brand relies on UI-in-UI: showing the product is the imagery.
+
+## Layout
+
+Full-bleed #101010 canvas at all times — no light body background. Max content width ~1200px, centered. Hero is a 2-column split: left third holds the headline + supporting copy + button row, right two-thirds holds the dashboard screenshot at near-1:1 scale. Section rhythm: dark band → logo strip → dark band with feature cards → dark band with CTA card. Vertical spacing between sections is 96px+ — the page breathes. Cards in grid layouts are separated by 24px gaps, never touching. Navigation is a single sticky top bar, no sidebar, no mega-menu — the surface stays uncluttered.
+
+## Agent Prompt Guide
+
+**Quick Color Reference**
+- canvas: #101010
+- text: #eeeeee
+- muted text: #8a8380
+- card surface: #eeeeee
+- accent (live status / data signal): #ee6018
+- accent (positive metric / trend): #a0ca92
+- primary action: #1d1a18 (filled action)
+
+**Example Component Prompts**
+1. *Hero section*: Full-bleed #101010 background, max-width 1200px centered. Headline at 72px Geist weight 400, #eeeeee, letter-spacing -2.88px, line-height 1. Supporting copy at 16px Geist weight 400, #8a8380. Two buttons inline: a dark filled button (#1f1d1c, #eeeeee text, 3px radius, 0 14px padding) followed by a ghost link with arrow (transparent, 1px #3d3a39 border, 0px radius, 24px vertical padding).
+2. Create a Primary Action Button: #1d1a18 background, #eeeeee text, 9999px radius, compact pill padding. Use this filled treatment for the main CTA.
+3. *Dashboard metric tile*: no background, 1px #1d1a18 bottom border, 20px padding. Label: Geist Mono 12px uppercase #b8b3b0. Value: Geist 36px weight 400, #eeeeee, letter-spacing -1.12px. Sparkline: 40px tall, 1px stroke, color #ee6018 (negative trend) or #a0ca92 (positive trend).
+4. *Trust logo strip*: full-width #101010 band, 96px vertical padding, single row of 8 partner wordmarks rendered in #8a8380, evenly distributed with 24px+ gaps. No card backgrounds, no dividers.
+5. *Top nav bar*: transparent on #101010, ~64px tall. Wordmark left: 'FACTORY' Geist Mono 12px uppercase #eeeeee. Nav center/right: Product, Enterprise, Pricing, News, Company, Careers in Geist 14px weight 400 #eeeeee uppercase. Log In button: #fafafa fill, #101010 text, 3px radius. Contact Sales: ghost text link with arrow.
+
+## Motion Philosophy
+
+Transitions are short and mechanical: 0.15s–0.2s with cubic-bezier(0.4, 0, 0.2, 1) easing — the feel of a CLI tool, not a marketing site. Color, background-color, border-color, and stroke all transition together so state changes feel like a single switch flipping, not a layered animation. Named motion (marquee-scroll, sfDashboardFrameIn) appears sparingly: a slow logo marquee and a single dashboard entrance. Avoid spring physics, parallax, or scroll-driven effects — the surface should feel still and precise.
+
+## Voice & Type Treatment
+
+Two voices, one family. Geist 400 carries all marketing and body copy — flat, calm, undecorated. Geist Mono 12px uppercase carries all instrument labels: column headers, status tags, 'BUILD WITH US', nav items. This split is structural: when a user sees Mono, they know they are looking at a system surface, not a page surface. Maintain this discipline even when extending the product.
+
+## Similar Brands
+
+- **Linear** — Same monochrome-dark canvas, weight-400 display type with tight negative tracking, and one restrained accent (Linear's purple vs Factory's orange) reserved for state and status, never decoration.
+- **Vercel** — Identical figure/ground strategy: pitch-black canvas, one bright card or screenshot as hero, Geist-family type at flat weight, no drop shadows — depth earned through contrast.
+- **Resend** — Shares the terminal-warm aesthetic — warm grays (#8a8380 class) instead of cold, Geist Mono labels, minimal radii (3–10px), and chromatic accents used only as functional signal in product UI.
+- **Cursor** — Developer-tool dark surface with Geist-weight typography, dashboard hero pattern showing the product in a windowed UI, and a single warm accent for active states.
+- **Railway** — Same instrument-panel sensibility — dark canvas, monospaced eyebrows, metric tiles with live data, and an anti-decorative stance that treats color as data not chrome.
+
+## Quick Start
+
+### CSS Custom Properties
+
+```css
+:root {
+  /* Colors */
+  --color-obsidian-canvas: #101010;
+  --color-carbon-lift: #1d1a18;
+  --color-ash-stroke: #3d3a39;
+  --color-graphite-mid: #4d4947;
+  --color-warm-granite: #8a8380;
+  --color-pale-stone: #b8b3b0;
+  --color-bone: #eeeeee;
+  --color-chalk: #fafafa;
+  --color-signal-orange: #ee6018;
+  --color-metric-green: #a0ca92;
+
+  /* Typography — Font Families */
+  --font-geist: 'Geist', ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  --font-geist-mono: 'Geist Mono', ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+
+  /* Typography — Scale */
+  --text-caption: 12px;
+  --leading-caption: 1;
+  --tracking-caption: -0.24px;
+  --text-body-sm: 14px;
+  --leading-body-sm: 1.43;
+  --text-body: 16px;
+  --leading-body: 1.5;
+  --text-heading: 36px;
+  --leading-heading: 1.1;
+  --tracking-heading: -1.12px;
+  --text-heading-lg: 44px;
+  --leading-heading-lg: 1.12;
+  --tracking-heading-lg: -1.1px;
+  --text-display: 72px;
+  --leading-display: 1;
+  --tracking-display: -2.88px;
+
+  /* Typography — Weights */
+  --font-weight-regular: 400;
+  --font-weight-medium: 500;
+
+  /* Spacing */
+  --spacing-unit: 8px;
+  --spacing-8: 8px;
+  --spacing-16: 16px;
+  --spacing-24: 24px;
+  --spacing-32: 32px;
+  --spacing-40: 40px;
+  --spacing-56: 56px;
+  --spacing-80: 80px;
+  --spacing-96: 96px;
+  --spacing-120: 120px;
+
+  /* Layout */
+  --page-max-width: 1200px;
+  --section-gap: 96px;
+  --card-padding: 24px;
+  --element-gap: 24px;
+
+  /* Border Radius */
+  --radius-sm: 3px;
+  --radius-lg: 10px;
+  --radius-2xl: 20px;
+
+  /* Named Radii */
+  --radius-nav: 3px;
+  --radius-cards: 10px;
+  --radius-buttons: 3px;
+  --radius-largepanels: 20px;
+
+  /* Surfaces */
+  --surface-obsidian-canvas: #101010;
+  --surface-carbon-lift: #1d1a18;
+  --surface-bone-card: #eeeeee;
+  --surface-chalk-elevated: #fafafa;
+}
+```
+
+### Tailwind v4
+
+```css
+@theme {
+  /* Colors */
+  --color-obsidian-canvas: #101010;
+  --color-carbon-lift: #1d1a18;
+  --color-ash-stroke: #3d3a39;
+  --color-graphite-mid: #4d4947;
+  --color-warm-granite: #8a8380;
+  --color-pale-stone: #b8b3b0;
+  --color-bone: #eeeeee;
+  --color-chalk: #fafafa;
+  --color-signal-orange: #ee6018;
+  --color-metric-green: #a0ca92;
+
+  /* Typography */
+  --font-geist: 'Geist', ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  --font-geist-mono: 'Geist Mono', ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+
+  /* Typography — Scale */
+  --text-caption: 12px;
+  --leading-caption: 1;
+  --tracking-caption: -0.24px;
+  --text-body-sm: 14px;
+  --leading-body-sm: 1.43;
+  --text-body: 16px;
+  --leading-body: 1.5;
+  --text-heading: 36px;
+  --leading-heading: 1.1;
+  --tracking-heading: -1.12px;
+  --text-heading-lg: 44px;
+  --leading-heading-lg: 1.12;
+  --tracking-heading-lg: -1.1px;
+  --text-display: 72px;
+  --leading-display: 1;
+  --tracking-display: -2.88px;
+
+  /* Spacing */
+  --spacing-8: 8px;
+  --spacing-16: 16px;
+  --spacing-24: 24px;
+  --spacing-32: 32px;
+  --spacing-40: 40px;
+  --spacing-56: 56px;
+  --spacing-80: 80px;
+  --spacing-96: 96px;
+  --spacing-120: 120px;
+
+  /* Border Radius */
+  --radius-sm: 3px;
+  --radius-lg: 10px;
+  --radius-2xl: 20px;
+}
+```

package/framework/styles/factory/README.md

@@ -0,0 +1,32 @@
+# Factory — Style Reference
+
+> terminal war room at midnight
+
+**Theme:** dark
+
+![Factory preview](./assets/preview.jpg)
+
+Factory is a stark black control surface: an Obsidian canvas, warm-gray supporting text, and a single light card that lands like a dispatch in the dark. Geist and Geist Mono typography, tight tracking, hairline borders, minimal radii, and generous spacing create an instrument-like interface. Signal orange and metric green are reserved for live status and data visualization rather than decorative chrome.
+
+## Guidelines
+
+### Do
+
+- Use #101010 as the page canvas and #eeeeee for the primary light-card surface
+- Use Geist at weight 400 for interface text; reserve weight 500 for focused emphasis
+- Use Geist Mono in uppercase for labels, status tags, and metric units
+- Reserve #ee6018 and #a0ca92 for live status, data signals, and chart strokes
+- Build depth through contrast, spacing, and 1px borders instead of shadows
+- Keep section gaps near 96px, card padding near 24px, and cards near 10px radius
+
+### Don't
+
+- Do not introduce additional accent colors
+- Do not use bold heading weights or loose editorial typography
+- Do not use orange or green as button, card, or large text fills
+- Do not add drop shadows, glows, or blur to create elevation
+- Do not use lifestyle photography or decorative gradients
+
+## Similar Brands
+
+Linear, Vercel, Resend, Cursor, Railway