@ulysses-ai/create-workspace 0.13.0-beta.0

package/template/.claude/skills/build-docs-site/templates/primitives/Arrow.tsx

@@ -0,0 +1,87 @@
+import React from 'react';
+import { colors, cls, layout, type StrokeClass } from './tokens';
+
+export interface ArrowProps {
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
+  /**
+   * If true, the arrow bends at a right angle.
+   * The corner is placed based on `elbowAxis`:
+   *   - 'horizontal-first': go horizontally to x2, then vertically to y2
+   *   - 'vertical-first':   go vertically to y2, then horizontally to x2
+   */
+  elbow?: boolean;
+  elbowAxis?: 'horizontal-first' | 'vertical-first';
+  strokeClass?: StrokeClass;
+  /** Override the marker fill. SVG markers can't be styled via parent CSS classes. */
+  markerColor?: string;
+  strokeWidth?: number;
+  dashed?: boolean;
+  /** Unique marker id suffix so multiple arrows can coexist with different colors. */
+  markerId?: string;
+}
+
+/**
+ * Note on arrowhead markers:
+ * SVG <marker> contents live in a shadow tree that does not inherit
+ * CSS classes from the host document. The marker fill must be a literal
+ * value. We default to the `text` color hex from tokens. If you need a
+ * theme-aware arrowhead, render two markers (one per theme) and switch
+ * via media query, or accept the cosmetic mismatch.
+ */
+export function Arrow({
+  x1,
+  y1,
+  x2,
+  y2,
+  elbow = false,
+  elbowAxis = 'horizontal-first',
+  strokeClass = 'strokeStrong',
+  markerColor = colors.text,
+  strokeWidth = layout.arrowStrokeWidth,
+  dashed = false,
+  markerId = 'default',
+}: ArrowProps) {
+  const id = `dx-arrowhead-${markerId}`;
+
+  let path: string;
+  if (elbow) {
+    if (elbowAxis === 'horizontal-first') {
+      path = `M ${x1} ${y1} L ${x2} ${y1} L ${x2} ${y2}`;
+    } else {
+      path = `M ${x1} ${y1} L ${x1} ${y2} L ${x2} ${y2}`;
+    }
+  } else {
+    path = `M ${x1} ${y1} L ${x2} ${y2}`;
+  }
+
+  return (
+    <g>
+      <defs>
+        <marker
+          id={id}
+          markerWidth={layout.arrowheadSize}
+          markerHeight={layout.arrowheadSize}
+          refX={layout.arrowheadSize - 1}
+          refY={layout.arrowheadSize / 2}
+          orient="auto-start-reverse"
+        >
+          <path
+            d={`M 0 0 L ${layout.arrowheadSize} ${layout.arrowheadSize / 2} L 0 ${layout.arrowheadSize} z`}
+            fill={markerColor}
+          />
+        </marker>
+      </defs>
+      <path
+        d={path}
+        fill="none"
+        className={cls.stroke[strokeClass]}
+        strokeWidth={strokeWidth}
+        strokeDasharray={dashed ? '4 3' : undefined}
+        markerEnd={`url(#${id})`}
+      />
+    </g>
+  );
+}

package/template/.claude/skills/build-docs-site/templates/primitives/Box.tsx

@@ -0,0 +1,90 @@
+import React from 'react';
+import { cls, layout, type FillClass, type StrokeClass } from './tokens';
+
+export type BoxVariant = 'default' | 'primary' | 'muted';
+
+export interface BoxProps {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  title?: string;
+  subtitle?: string;
+  variant?: BoxVariant;
+  fillClass?: FillClass;
+  strokeClass?: StrokeClass;
+  textClass?: FillClass;
+  rx?: number;
+}
+
+const variantMap: Record<BoxVariant, { fill: FillClass; stroke: StrokeClass; text: FillClass }> = {
+  default: { fill: 'surface', stroke: 'stroke', text: 'text' },
+  primary: { fill: 'primary', stroke: 'primary', text: 'surface' },
+  muted: { fill: 'surfaceStrong', stroke: 'stroke', text: 'textMuted' },
+};
+
+export function Box({
+  x,
+  y,
+  width,
+  height,
+  title,
+  subtitle,
+  variant = 'default',
+  fillClass,
+  strokeClass,
+  textClass,
+  rx = layout.boxRadius,
+}: BoxProps) {
+  const v = variantMap[variant];
+  const fill = fillClass ?? v.fill;
+  const stroke = strokeClass ?? v.stroke;
+  const text = textClass ?? v.text;
+
+  const cx = x + width / 2;
+  const titleY = subtitle ? y + height / 2 - 4 : y + height / 2 + 4;
+  const subtitleY = y + height / 2 + 12;
+
+  return (
+    <g>
+      <rect
+        x={x}
+        y={y}
+        width={width}
+        height={height}
+        rx={rx}
+        ry={rx}
+        className={`${cls.fill[fill]} ${cls.stroke[stroke]}`}
+        strokeWidth={layout.boxStrokeWidth}
+      />
+      {title && (
+        <text
+          x={cx}
+          y={titleY}
+          textAnchor="middle"
+          dominantBaseline="middle"
+          fontSize={layout.titleFontSize}
+          fontFamily={layout.fontFamily}
+          fontWeight={600}
+          className={cls.fill[text]}
+        >
+          {title}
+        </text>
+      )}
+      {subtitle && (
+        <text
+          x={cx}
+          y={subtitleY}
+          textAnchor="middle"
+          dominantBaseline="middle"
+          fontSize={layout.subtitleFontSize}
+          fontFamily={layout.fontFamily}
+          className={cls.fill[text]}
+          opacity={0.75}
+        >
+          {subtitle}
+        </text>
+      )}
+    </g>
+  );
+}

package/template/.claude/skills/build-docs-site/templates/primitives/DiagramContainer.tsx

@@ -0,0 +1,46 @@
+import React from 'react';
+
+export interface DiagramContainerProps {
+  /** SVG viewport width in pixels. */
+  width: number;
+  /** SVG viewport height in pixels. */
+  height: number;
+  /** Optional caption shown below the diagram. */
+  caption?: string;
+  /** Optional accessible label for the diagram. */
+  ariaLabel?: string;
+  children: React.ReactNode;
+}
+
+/**
+ * Outer wrapper for every diagram in the documentation site.
+ *
+ * Provides:
+ *   - Consistent padding via the `dx-diagram-container` CSS class
+ *   - Theme-aware background (light cream / dark surface) defined in custom.css
+ *   - Caption rendering below the diagram
+ *   - Accessible labelling
+ *   - viewBox-based responsive sizing (the SVG scales to its container)
+ */
+export function DiagramContainer({
+  width,
+  height,
+  caption,
+  ariaLabel,
+  children,
+}: DiagramContainerProps) {
+  return (
+    <figure className="dx-diagram-container">
+      <svg
+        viewBox={`0 0 ${width} ${height}`}
+        xmlns="http://www.w3.org/2000/svg"
+        role="img"
+        aria-label={ariaLabel ?? caption ?? 'Diagram'}
+        preserveAspectRatio="xMidYMid meet"
+      >
+        {children}
+      </svg>
+      {caption && <figcaption className="dx-diagram-caption">{caption}</figcaption>}
+    </figure>
+  );
+}

package/template/.claude/skills/build-docs-site/templates/primitives/Region.tsx

@@ -0,0 +1,68 @@
+import React from 'react';
+import { cls, layout, type FillClass, type StrokeClass } from './tokens';
+
+export interface RegionProps {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  label?: string;
+  fillClass?: FillClass;
+  strokeClass?: StrokeClass;
+  labelClass?: FillClass;
+  dashed?: boolean;
+  rx?: number;
+  children?: React.ReactNode;
+}
+
+/**
+ * A grouped, labelled container that visually scopes a set of related
+ * elements. Use Region when you want to show "these things belong
+ * together" without committing to a Box-as-foreground meaning.
+ *
+ * The label sits above the top-left corner of the region.
+ * Children render inside the region's coordinate space.
+ */
+export function Region({
+  x,
+  y,
+  width,
+  height,
+  label,
+  fillClass = 'surfaceStrong',
+  strokeClass = 'stroke',
+  labelClass = 'textMuted',
+  dashed = true,
+  rx = layout.boxRadius,
+  children,
+}: RegionProps) {
+  return (
+    <g>
+      <rect
+        x={x}
+        y={y}
+        width={width}
+        height={height}
+        rx={rx}
+        ry={rx}
+        className={`${cls.fill[fillClass]} ${cls.stroke[strokeClass]}`}
+        strokeWidth={layout.boxStrokeWidth}
+        strokeDasharray={dashed ? '4 3' : undefined}
+        opacity={0.4}
+      />
+      {label && (
+        <text
+          x={x + 8}
+          y={y - 6}
+          fontSize={layout.captionFontSize}
+          fontFamily={layout.fontFamily}
+          fontWeight={600}
+          className={cls.fill[labelClass]}
+        >
+          {label}
+        </text>
+      )}
+      {children}
+    </g>
+  );
+}

package/template/.claude/skills/build-docs-site/templates/primitives/SectionTitle.tsx

@@ -0,0 +1,42 @@
+import React from 'react';
+import { cls, layout, type FillClass } from './tokens';
+
+export interface SectionTitleProps {
+  x: number;
+  y: number;
+  text: string;
+  textClass?: FillClass;
+  fontSize?: number;
+  align?: 'start' | 'middle' | 'end';
+  bold?: boolean;
+}
+
+/**
+ * A caption or section heading inside an SVG diagram.
+ * Use this for labels above a region or row, not for box titles
+ * (which are handled by Box's own title prop).
+ */
+export function SectionTitle({
+  x,
+  y,
+  text,
+  textClass = 'text',
+  fontSize = layout.captionFontSize,
+  align = 'start',
+  bold = true,
+}: SectionTitleProps) {
+  return (
+    <text
+      x={x}
+      y={y}
+      textAnchor={align}
+      dominantBaseline="middle"
+      fontSize={fontSize}
+      fontFamily={layout.fontFamily}
+      fontWeight={bold ? 600 : 400}
+      className={cls.fill[textClass]}
+    >
+      {text}
+    </text>
+  );
+}

package/template/.claude/skills/build-docs-site/templates/primitives/tokens.ts

@@ -0,0 +1,67 @@
+/**
+ * Diagram tokens for the build-docs-site skill.
+ *
+ * Two exports:
+ *   - `colors`: hex values, used where class-based styling can't reach
+ *     (e.g., SVG <marker> contents in shadow tree).
+ *   - `cls`: class name maps, used everywhere else. The matching CSS
+ *     classes are defined in the site's custom.css.
+ *
+ * Why class names instead of CSS variables in fill/stroke attributes:
+ * Chromium's SVG paint pipeline does not reliably resolve
+ * `fill="var(--x)"` or `style={{fill: 'var(--x)'}}`. Class selectors
+ * with `fill: var(--x)` rules work consistently because the cascade
+ * resolves the variable before paint.
+ */
+
+export const colors = {
+  // Semantic colors — light mode hex fallbacks.
+  // Kept in sync with --dx-* CSS variables in custom.css.
+  primary: '#3B6EA8',
+  accent: '#D97757',
+  surface: '#FFFFFF',
+  surfaceStrong: '#F2F2F2',
+  text: '#1A1A1A',
+  textMuted: '#666666',
+  stroke: '#CCCCCC',
+  strokeStrong: '#888888',
+} as const;
+
+export const cls = {
+  fill: {
+    primary: 'dx-fill-primary',
+    accent: 'dx-fill-accent',
+    surface: 'dx-fill-surface',
+    surfaceStrong: 'dx-fill-surface-strong',
+    text: 'dx-fill-text',
+    textMuted: 'dx-fill-text-muted',
+    stroke: 'dx-fill-stroke',
+    strokeStrong: 'dx-fill-stroke-strong',
+  },
+  stroke: {
+    primary: 'dx-stroke-primary',
+    accent: 'dx-stroke-accent',
+    surface: 'dx-stroke-surface',
+    surfaceStrong: 'dx-stroke-surface-strong',
+    text: 'dx-stroke-text',
+    textMuted: 'dx-stroke-text-muted',
+    stroke: 'dx-stroke-stroke',
+    strokeStrong: 'dx-stroke-stroke-strong',
+  },
+} as const;
+
+export type ColorToken = keyof typeof colors;
+export type FillClass = keyof typeof cls.fill;
+export type StrokeClass = keyof typeof cls.stroke;
+
+// Layout constants shared across primitives.
+export const layout = {
+  boxRadius: 6,
+  boxStrokeWidth: 1.5,
+  arrowStrokeWidth: 1.5,
+  arrowheadSize: 8,
+  titleFontSize: 14,
+  subtitleFontSize: 11,
+  captionFontSize: 12,
+  fontFamily: 'inherit',
+} as const;

package/template/.claude/skills/build-docs-site/templates/sidebars.ts.tmpl

@@ -0,0 +1,89 @@
+import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
+
+/**
+ * Sidebar configuration for the documentation site.
+ *
+ * The build-docs-site skill replaces the placeholder structure below
+ * based on the user's Phase 1 answers (audience, structure, chapters).
+ *
+ * Patterns to know:
+ *
+ *   1. Clickable category labels — use `link: { type: 'doc', id: 'overview-doc-id' }`
+ *      so clicking the category itself navigates to its overview page.
+ *
+ *   2. Generated category index — alternative when no overview doc exists:
+ *      `link: { type: 'generated-index' }` auto-builds an index page from
+ *      the category's children.
+ *
+ *   3. Nested categories — categories can contain other categories.
+ *      Use sparingly; deep nesting hurts navigation.
+ *
+ *   4. Doc IDs — paths are relative to the docs/ directory, without
+ *      the .md or .mdx extension.
+ *
+ * Replace the placeholder structure with the real chapter list during
+ * Phase 4 scaffold. The skill writes one entry per chapter from the spec.
+ */
+
+const sidebars: SidebarsConfig = {
+  docs: [
+    'index', // The site's root page (slug: /)
+
+    {
+      type: 'category',
+      label: 'Part I — Foundations',
+      link: {
+        type: 'doc',
+        id: 'part-1/overview',
+      },
+      items: [
+        'part-1/chapter-1',
+        'part-1/chapter-2',
+        'part-1/chapter-3',
+      ],
+    },
+
+    {
+      type: 'category',
+      label: 'Part II — Systems',
+      link: {
+        type: 'doc',
+        id: 'part-2/overview',
+      },
+      items: [
+        'part-2/chapter-4',
+        'part-2/chapter-5',
+        // For long chapters, use nested categories with their own clickable label:
+        // {
+        //   type: 'category',
+        //   label: 'Chapter N — Title',
+        //   link: { type: 'doc', id: 'part-2/chapter-n/overview' },
+        //   items: ['part-2/chapter-n/topic-a', 'part-2/chapter-n/topic-b'],
+        // },
+      ],
+    },
+
+    {
+      type: 'category',
+      label: 'Part III — Integration',
+      link: {
+        type: 'doc',
+        id: 'part-3/overview',
+      },
+      items: [
+        'part-3/chapter-final',
+      ],
+    },
+
+    {
+      type: 'category',
+      label: 'Appendices',
+      items: [
+        'appendix/glossary',
+        'appendix/tech-stack',
+      ],
+    },
+  ],
+};
+
+export default sidebars;

package/template/.claude/skills/build-docs-site/templates/spec.md.tmpl

@@ -0,0 +1,119 @@
+---
+state: ephemeral
+lifecycle: active
+type: design
+topic: docs-site
+author: {{USER}}
+updated: {{DATE}}
+---
+
+# Documentation Site Spec — {{PROJECT_NAME}}
+
+Specification for the documentation site to be built by `/build-docs-site`. Generated from Phase 1 framing answers, Phase 2 source inventory, and review of the project's existing material.
+
+## Purpose
+
+{{PURPOSE_PARAGRAPH}}
+
+The site replaces the existing scattered documentation listed in the migration mapping below. Old material is treated as source content; the new site is the authoritative reference going forward.
+
+## Audience
+
+**Primary:** {{AUDIENCE_PRIMARY}}
+
+{{AUDIENCE_NOTES}}
+
+The audience shapes tone, depth, and what counts as an implementation-detail leak (Phase 6 review).
+
+## Reading pattern
+
+**Engagement style:** {{ENGAGEMENT_STYLE}}
+**Content cohesion:** {{CONTENT_COHESION}}
+**Chapter split threshold:** {{CHAPTER_SPLIT_THRESHOLD}} lines
+
+These shape how chapters are sized and when long chapters get split into Docusaurus categories with sub-pages.
+
+## Structure
+
+{{STRUCTURE_TYPE}}
+
+### Parts and chapters
+
+{{CHAPTER_LIST}}
+
+Each chapter has a one-paragraph synopsis. Chapter 1 is written last (technical-writing convention — the opener benefits from being written with full authority over what the rest says).
+
+## Existing documentation mapping
+
+This table lists every existing doc that was identified in Phase 1 and what it maps to in the new site. The act of writing the new site IS the migration — these old files become source material and are replaced when the site is complete.
+
+| Old file | Topic | Quality | New chapter | Status |
+|----------|-------|---------|-------------|--------|
+{{MAPPING_ROWS}}
+
+Quality categories: `sparse` (thin or stub), `adequate` (covers the topic but could be better), `comprehensive` (good content, just disorganized), `outdated` (was good but is now wrong).
+
+After Phase 6 coverage check passes, files marked as `replaced` are safe to delete.
+
+## Source inventory
+
+Beyond the existing documentation, the following sources feed into the new site:
+
+{{SOURCE_INVENTORY}}
+
+## Brand and style
+
+**Identity source:** {{BRAND_SOURCE}}
+
+**Colors:**
+- Primary: {{BRAND_PRIMARY}}
+- Accent: {{BRAND_ACCENT}}
+- Background (light): {{BRAND_BACKGROUND}}
+- Background (dark): {{BRAND_BACKGROUND_DARK}}
+
+**Fonts:**
+- Headings: {{BRAND_FONT_HEADING}}
+- Body: {{BRAND_FONT_BODY}}
+- Monospace: {{BRAND_FONT_MONO}}
+
+**Voice and tone:**
+{{BRAND_VOICE}}
+
+## Language constraints
+
+Words, phrases, or framings to avoid throughout the documentation. The forbidden-word grep in Phase 6 uses this list.
+
+{{LANGUAGE_CONSTRAINTS}}
+
+## Research treatment
+
+**Research timing:** {{RESEARCH_TIMING}}
+**Designed vs built:** {{DESIGNED_VS_BUILT}}
+
+{{RESEARCH_NOTES}}
+
+## Diagrams plan
+
+Initial diagram stubs by chapter. Fleshed out before Phase 7 (diagrams). Diagrams may be reused across chapters when they show the same concept.
+
+{{DIAGRAM_STUBS}}
+
+## Implementation-detail rule
+
+The documentation describes concepts and roles, not library choices. Library names, framework names, and model names appear only in the Tech Stack appendix unless the choice itself is architecturally meaningful.
+
+The Phase 6 leak grep derives its detection list from the project's own dependency manifests (`package.json`, `pyproject.toml`, etc.) plus any project-specific terms added below.
+
+**Project-specific terms to flag:**
+
+{{PROJECT_LEAK_TERMS}}
+
+## Brainstorm-acronym translations
+
+Terms that came from brainstorming sessions and need to be translated to descriptive names in the documentation. The descriptive name leads; the acronym (if useful) survives only as a parenthetical shorthand.
+
+{{ACRONYM_TRANSLATIONS}}
+
+## Notes
+
+This spec is consumed by `/complete-work` into release notes when the session finishes. Update it as decisions change during writing.