docs(reed): skill accuracy + cost model + feedback channel

gt-va003, gt-va006, gt-va007 / convoy-032

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: auge2u

commands/feedback.md

@@ -0,0 +1,85 @@
+# feedback — Issue Reporting
+
+> Standalone command · No frame dependency
+> Read-only by default — writes a report file with user confirmation
+
+---
+
+## What this command does
+
+Generates a structured report when a skill produces unexpected output. Use this
+when tokens don't render correctly, CSS conflicts with existing styles, RLS
+policies don't apply as expected, or any step doesn't work as documented.
+
+---
+
+## When to use
+
+- Token colors differ from the swatch preview or cultural source
+- Dark mode doesn't toggle or has missing semantic mappings
+- CSS conflicts with existing styles after importing a theme
+- RLS policies don't isolate tenant data as expected
+- Auth graduation fails to promote a user to the next level
+- Any skill instruction produces a different result than described
+
+---
+
+## What it captures
+
+The feedback command generates a structured report based on the current session
+context:
+
+- **Skill used**: Which skill or command was active when the issue occurred
+- **Step that failed**: The specific instruction that didn't produce the expected result
+- **Error observed**: What happened vs. what was expected
+- **Workaround applied**: How you resolved it (if you did)
+- **Environment**: Package versions, OS, runtime, Tailwind version
+
+---
+
+## Output
+
+The report is written to `.platform/feedback/YYYY-MM-DD-<slug>.md` in your
+project directory. The slug is derived from the skill name and a short
+description of the issue.
+
+Example path: `.platform/feedback/2026-02-22-theme-tokens-dark-mode-missing.md`
+
+---
+
+## Optional: submit to the platform team
+
+With user consent, the feedback command can open a GitHub issue on
+`syncupsuite/webplatform4sync` containing the report. The user reviews the
+full issue content before submission — nothing is sent without confirmation.
+
+To submit:
+
+```bash
+gh issue create --repo syncupsuite/webplatform4sync \
+  --title "Feedback: <skill> — <short description>" \
+  --body-file .platform/feedback/YYYY-MM-DD-<slug>.md
+```
+
+---
+
+## Why this exists
+
+This is Layer 4 of the design taxonomy (Token Engine -> Curated Packs ->
+Design Identity -> Feedback Channel). When an LLM uses a skill and something
+doesn't work, that information needs a structured path back to the platform
+team. Without it, the same issues recur across projects and the skills don't
+improve.
+
+---
+
+## Routing
+
+This is a standalone command. It reads the following skills for context:
+
+| Resource | Path |
+|----------|------|
+| Token skill | `skills/theme-inspired-tokens/skill.md` |
+| Multi-tenant skill | `skills/multi-tenant-platform/skill.md` |
+| Auth skill | `skills/graduated-auth/skill.md` |
+| Neon skill | `skills/neon-multi-tenant/skill.md` |

skills/multi-tenant-platform/skill.md

@@ -51,9 +51,9 @@ These rules apply to every project that uses this skill, regardless of complexit
 
 2. **Defense-in-depth isolation.** Never rely on a single layer. Combine: application-level filtering + PostgreSQL RLS + connection-level context (`SET app.tenant_id`). If one layer fails, the others catch it.
 
-3. **Semantic tokens only.** UI components never reference raw colors or hardcoded values. All theming goes through semantic design tokens (`--color-surface-primary`, not `--blue-500`).
+3. **Semantic tokens only.** UI components should not reference raw colors or hardcoded values. All theming goes through semantic design tokens (`--color-surface-primary`, not `--blue-500`).
 
-4. **Protected tokens.** Certain tokens (accessibility contrast ratios, minimum font sizes, spacing rhythm) are platform-controlled and cannot be overridden by T1 or T2 themes.
+4. **Protected tokens.** Certain tokens (accessibility contrast ratios, minimum font sizes, spacing rhythm) are platform-controlled and cannot be overridden by T1 or T2 themes. This exists for compliance and accessibility: status colors must remain distinguishable for colorblind users, focus indicators must meet WCAG 2.1 requirements, and spacing rhythm must preserve readability. Without protection, a single tenant's brand override could break accessibility for their entire user base.
 
 5. **WCAG AA minimum.** All tenant themes must pass WCAG AA contrast checks. The platform enforces this at token generation time, not at runtime.
 
@@ -209,6 +209,81 @@ All projects using this skill target:
 
 ---
 
+## Why This Structure
+
+The 3-tier model maps to a specific cost structure. Understanding this helps with capacity planning.
+
+- **Shared Neon database**: One database project with branch isolation for dev/preview environments. You pay for one database, not one per tenant. Neon branches are copy-on-write, so storage is shared for unchanged data.
+- **Hyperdrive connection pooling**: One Hyperdrive configuration serves all tenants at the edge. Workers reuse pooled TCP connections instead of opening new ones per request. This avoids per-tenant connection overhead.
+- **Single Worker deployment**: One codebase deployed to Cloudflare Workers. Tenant identity is resolved at request time from the hostname or session. There is no per-tenant deployment step.
+- **Token CSS via CDN**: Theme CSS files are static assets served from the edge cache. Switching tenants swaps a CSS import, not a server-side render.
+
+The result: infrastructure costs stay roughly flat as tenant count grows. Adding a new T2 tenant is a database row and a DNS record, not a new deployment. The cost scales with traffic and storage, not with tenant count.
+
+---
+
+## Multi-Domain Tenant Resolution
+
+When tenants operate under their own domains (white-label), the platform resolves tenant identity from the incoming request hostname.
+
+### Domain Mappings
+
+Each tenant can have multiple domains with different roles:
+
+```typescript
+// Domain type enum
+type DomainType = 'primary' | 'alias' | 'vanity';
+
+// Domain mapping record
+interface DomainMapping {
+  domain: string;        // e.g., "app.clientbrand.com"
+  tenant_id: string;     // Resolved tenant
+  domain_type: DomainType;
+  verified: boolean;     // DNS ownership confirmed
+  ssl_status: string;    // Certificate provisioning state
+}
+```
+
+| Type | Purpose | Example |
+|------|---------|---------|
+| `primary` | The canonical domain for the tenant | `app.clientbrand.com` |
+| `alias` | Alternative domains that resolve to the same tenant | `clientbrand.example.com` |
+| `vanity` | Short or branded URLs for specific features | `go.clientbrand.com` |
+
+### Tenant Resolution Middleware
+
+On every incoming request, the Worker resolves the tenant before any application logic runs:
+
+1. Extract hostname from the request
+2. Look up `domain_mappings` for a matching, verified domain
+3. If found, set `tenant_id` in the request context
+4. If not found, fall back to the platform's default domain handling (show landing page or 404)
+
+```typescript
+// Simplified resolution flow
+async function resolveTenant(request: Request, db: DrizzleClient): Promise<string | null> {
+  const hostname = new URL(request.url).hostname;
+  const mapping = await db.select()
+    .from(domainMappings)
+    .where(and(
+      eq(domainMappings.domain, hostname),
+      eq(domainMappings.verified, true)
+    ))
+    .limit(1);
+  return mapping[0]?.tenant_id ?? null;
+}
+```
+
+Domain verification uses a DNS TXT record: the tenant adds a `_syncup-verify.domain.com` TXT record containing a platform-issued token. The platform checks this before marking the domain as verified.
+
+---
+
+## Reporting Issues
+
+If RLS policies don't apply as expected or tenant isolation fails during testing, use the `feedback` command to capture the issue for the platform team.
+
+---
+
 ## Related Skills
 
 - `theme-inspired-tokens` -- Design token generation and cultural compliance

skills/neon-multi-tenant/skill.md

@@ -162,7 +162,7 @@ await db.insert(documents).values({ title: 'New Doc' }); // tenant_id injected
 
 ## Hyperdrive Connection Pooling
 
-Cloudflare Hyperdrive provides connection pooling at the edge, eliminating cold-start connection overhead for Neon. This is critical for Workers because:
+Cloudflare Hyperdrive provides connection pooling at the edge, reducing cold-start connection overhead for Neon. This matters for Workers because:
 
 - Each Worker invocation would otherwise create a new TCP + TLS connection to Neon.
 - Neon's serverless driver uses WebSocket, but Hyperdrive uses persistent TCP connections from Cloudflare's network.
@@ -176,6 +176,8 @@ Cloudflare Hyperdrive provides connection pooling at the edge, eliminating cold-
 | First query latency | 80-200ms | 10-30ms |
 | Sustained query latency | 20-50ms | 10-30ms |
 
+**Cost note**: Neon's free tier supports this branch-based isolation model for development and early production. As tenant count grows, costs scale through connection pooling (Hyperdrive) and storage, not through per-tenant database provisioning. Adding a T2 tenant is a row in the database and an RLS policy, not a new Neon branch.
+
 See `templates/hyperdrive-setup.md` for configuration details.
 
 ---

skills/theme-inspired-tokens/references/theme-registry.md

@@ -200,6 +200,143 @@ To use a foundation, pass its `id` to the skill: `--theme nihon-no-iro-tradition
 
 ---
 
+### 8. France / International: Art Deco
+
+| Field | Value |
+|-------|-------|
+| **ID** | `art-deco-international` |
+| **Name** | Art Deco (Arts Decoratifs) |
+| **Story** | Originating from the 1925 Exposition Internationale des Arts Decoratifs et Industriels Modernes in Paris, Art Deco fused geometric precision with luxury materials. The movement spread globally through architecture (Chrysler Building), fashion (Erté), and graphic design (Cassandre's posters). Its palette combines metallic golds and silvers with deep saturated jewel tones, always arranged in symmetrical, angular compositions. |
+| **Philosophy** | Modernized opulence: machine-age geometry applied to decorative arts. Order and symmetry as expressions of progress. |
+| **Era** | 1920s-1930s, with revival periods in the 1960s and 2010s |
+
+**Seed Colors**:
+
+| Name | Native | Hex | Provenance |
+|------|--------|-----|------------|
+| Or Champagne | Champagne Gold | `#D4AF37` | The gilded surfaces of Art Deco interiors -- not bright gold but the warm patina of aged brass and gold leaf on plaster reliefs. |
+| Noir Onyx | Onyx Black | `#1A1A1A` | Polished black lacquer, the backdrop for geometric inlays. From Japanese lacquerware adopted by French decorators. |
+| Bleu Saphir | Sapphire Blue | `#0F3B82` | Deep sapphire, the jewel tone of stained glass in Art Deco churches (Sainte-Odile, Paris) and Lalique glasswork. |
+| Vert Jade | Jade Green | `#00786A` | Jade green from the Chinese and Egyptian artifacts that inspired Art Deco's cross-cultural ornament vocabulary. |
+| Ivoire | Ivory | `#F5F0E1` | The warm white of carved ivory inlays in Art Deco furniture by Emile-Jacques Ruhlmann. |
+| Rouille | Rust | `#A0522D` | Oxidized copper and Cor-Ten steel, the warm brown that grounds Deco's metallic palette. |
+
+**Suggested Harmony**: Complementary (bold contrasts between jewel tones and metallics)
+
+**Radius Tendency**: None to small (sm) -- angular geometry, chamfered corners rather than curves
+
+---
+
+### 9. Austria: Wiener Werkstatte
+
+| Field | Value |
+|-------|-------|
+| **ID** | `wiener-werkstaette` |
+| **Name** | Wiener Werkstatte (Vienna Workshops) |
+| **Story** | Founded in 1903 by Josef Hoffmann and Koloman Moser, the Wiener Werkstatte pursued Gesamtkunstwerk (total work of art) -- designing everything from buildings to teaspoons. The workshop's visual language combined Secessionist flowing lines with a distinctive grid-based ornamental system. Black and white geometric patterns, accented with primary colors, became the workshop's signature through textiles, ceramics, and graphic design. |
+| **Philosophy** | Gesamtkunstwerk: every element of the environment is designed as part of a unified whole. Craft and art are indistinguishable. |
+| **Era** | 1903-1932, Vienna Secession and early Modernism |
+
+**Seed Colors**:
+
+| Name | Native | Hex | Provenance |
+|------|--------|-----|------------|
+| Schwarz | Black | `#1C1C1C` | The black of Hoffmann's grid patterns and Moser's graphic work. Structural, not decorative. |
+| Weiss | White | `#F4F0E8` | The off-white of Viennese stucco and the Werkstatte's unglazed ceramics. Warm, not clinical. |
+| Schachbrett-Gold | Checkerboard Gold | `#C5A55A` | The gilt surfaces of the Palais Stoclet in Brussels, Hoffmann's most complete Gesamtkunstwerk. |
+| Klimt-Rot | Klimt Red | `#A02C2C` | The warm red of Gustav Klimt's decorative panels, closely associated with the Secession movement. |
+| Silbergrau | Silver Gray | `#8A8A82` | Hammered silver metalwork by Hoffmann -- matte, textured, never polished to a mirror finish. |
+
+**Suggested Harmony**: Monochromatic with accent (black/white/gray foundation, selective color accents)
+
+**Radius Tendency**: None (strict geometry -- the Hoffmann grid is rectilinear)
+
+---
+
+### 10. Italy: Milanese Design
+
+| Field | Value |
+|-------|-------|
+| **ID** | `milanese-design` |
+| **Name** | Milanese Design (Design Italiano) |
+| **Story** | Milan became the global capital of industrial design in the postwar period through the work of Gio Ponti, Achille Castiglioni, and the studios that supplied Olivetti, Alessi, and Kartell. Italian design balanced engineering precision with playful color and sculptural form. The Compasso d'Oro awards, established in 1954, codified the movement's values: utility, beauty, and production quality as inseparable concerns. |
+| **Philosophy** | Bel design: beauty is not applied to function but emerges from it. Industrial objects deserve the same design attention as fine art. |
+| **Era** | 1950s-1980s, Milan-centered Italian industrial design |
+
+**Seed Colors**:
+
+| Name | Native | Hex | Provenance |
+|------|--------|-----|------------|
+| Rosso Olivetti | Olivetti Red | `#D43B2E` | The red of the Olivetti Valentine typewriter (1969), designed by Ettore Sottsass. A deliberate break from office-machine gray. |
+| Bianco Carrara | Carrara White | `#F0EDE6` | The warm white of Carrara marble, quarried in Tuscany since Roman times and used in everything from Michelangelo's David to Milanese kitchen countertops. |
+| Grigio Milano | Milan Gray | `#6B6B67` | The concrete and stone gray of Milanese architecture -- restrained, urban, a backdrop for designed objects. |
+| Blu Ponti | Ponti Blue | `#1D5B8E` | The ceramic blue of Gio Ponti's tile work for the Hotel Parco dei Principi in Sorrento (1960). Mediterranean but measured. |
+| Arancione Kartell | Kartell Orange | `#E07028` | The injection-molded plastic orange of Kartell's furniture line -- democratic material, vivid color. |
+| Nero Assoluto | Absolute Black | `#1A1A1E` | The polished granite black of Italian luxury goods -- Brionvega televisions, Artemide lamps. |
+
+**Suggested Harmony**: Triadic (bold, saturated palette reflecting Italian design's confidence with color)
+
+**Radius Tendency**: Medium (md to lg) -- sculptural, organic curves from Castiglioni's industrial forms
+
+---
+
+## The Netherlands
+
+### 11. De Stijl
+
+| Field | Value |
+|-------|-------|
+| **ID** | `de-stijl-movement` |
+| **Name** | De Stijl (The Style) |
+| **Story** | Founded in 1917 by Theo van Doesburg and Piet Mondrian, De Stijl reduced visual language to its most fundamental elements: straight lines, right angles, and three primary colors plus black and white. The movement influenced architecture (Rietveld Schroder House), furniture (Red Blue Chair), and graphic design. Its radical abstraction argued that universal harmony could be expressed through pure geometric relationships. |
+| **Philosophy** | Neoplasticism: universal beauty through the reduction of form to horizontal and vertical lines, and color to the three primaries plus neutrals. |
+| **Era** | 1917-1931, Dutch avant-garde |
+
+**Seed Colors**:
+
+| Name | Native | Hex | Provenance |
+|------|--------|-----|------------|
+| Mondriaan Rood | Mondrian Red | `#CC1C1C` | The red of Mondrian's Composition paintings -- a specific warm red, slightly darker than fire-engine red, applied in flat, bounded planes. |
+| Mondriaan Blauw | Mondrian Blue | `#1C3D8F` | A deep, slightly warm ultramarine. In Mondrian's compositions, blue planes are typically smaller than red, creating asymmetric visual weight. |
+| Mondriaan Geel | Mondrian Yellow | `#F0C800` | A strong cadmium-adjacent yellow. The lightest primary, often given the largest area in Mondrian's late compositions. |
+| Zwart | Black | `#0A0A0A` | The black of De Stijl's grid lines -- not gray, not softened. The structural element that defines all spatial relationships. |
+| Wit | White | `#F5F5F5` | The white ground of Mondrian's compositions. More area than any single color, white is a compositional element, not empty space. |
+
+**Suggested Harmony**: Complementary (primary colors in deliberate tension, as De Stijl intended)
+
+**Radius Tendency**: None (strict right angles only -- any curve would violate Neoplastic principles)
+
+---
+
+## Switzerland (Modern)
+
+### 12. Swiss Modernist
+
+| Field | Value |
+|-------|-------|
+| **ID** | `swiss-modernist` |
+| **Name** | Swiss Modernist Design |
+| **Story** | Building on the International Typographic Style of the 1950s but extending into the late 20th century, Swiss Modernist design integrated new printing technologies and color systems while maintaining the discipline of the grid. Designers like Wolfgang Weingart (the "father of New Wave typography") and Wim Crouwel pushed Swiss principles toward greater expressiveness while retaining structural rigor. The palette expanded beyond strict black-red-white to include systematic use of color as information. |
+| **Philosophy** | Structured expression: the grid is not a cage but a framework for controlled variation. Precision and personality coexist. |
+| **Era** | 1970s-1990s, evolving from the International Typographic Style |
+
+**Seed Colors**:
+
+| Name | Native | Hex | Provenance |
+|------|--------|-----|------------|
+| Signalrot | Signal Red | `#E03030` | Derived from Swiss SBB railway signage -- a functional red used for warnings and emphasis. Slightly warmer than the federal flag red. |
+| Nachtschwarz | Night Black | `#181818` | The dense black of offset-printed posters by Weingart and Muller-Brockmann. Ink-dense, not screen-gray. |
+| Papierweiss | Paper White | `#F8F6F0` | The warm white of uncoated Swiss paper stock -- Lessebo, Munken -- with a tactile quality distinct from coated bright white. |
+| Himmelblau | Sky Blue | `#3A7BBF` | Informational blue from Swiss transit maps and wayfinding systems. Functional, high-visibility, paired with white for legibility. |
+| Mittelgrau | Medium Gray | `#717171` | The typographic gray -- the perceived value of a page of body text. A functional neutral. |
+| Signalgelb | Signal Yellow | `#F0C020` | From SBB train livery and Swiss postal branding. A functional accent color for highlighting and warnings. |
+
+**Suggested Harmony**: Golden Ratio (systematic color generation within a structured framework)
+
+**Radius Tendency**: None to small (sm) -- grid-based geometry with occasional softened corners for interactive elements
+
+---
+
 ## Using Custom Foundations
 
 If none of the registered foundations match your project, you can define a custom one. Provide all required fields from the Theme Source layer in `skill.md`: