studiograph 1.1.3 → 1.2.0-beta.10

package/dist/agent/skill-loader.js

@@ -0,0 +1,166 @@
+/**
+ * Skill Loader — prompt skills for the Studiograph agent.
+ *
+ * Skills are markdown files with YAML frontmatter that inject domain-specific
+ * knowledge into the agent's system prompt. Two formats supported:
+ *
+ *   Directory skill:
+ *     skills/create-deck/
+ *       skill.md        ← required entrypoint
+ *       slide-types.md  ← optional sub-files
+ *
+ *   Single-file skill:
+ *     skills/quick-tip.md
+ *
+ * Frontmatter fields:
+ *   name:        kebab-case identifier (defaults to directory/filename)
+ *   description: shown in skill index so agent knows when to load it
+ *   loading:     "on-demand" (default) | "eager" (inlined in system prompt)
+ */
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { join, extname, basename } from 'path';
+/**
+ * Minimal YAML frontmatter parser — handles the subset used by skills.
+ */
+function parseFrontmatter(content) {
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+    if (!match) {
+        return { meta: {}, body: content };
+    }
+    const meta = {};
+    for (const line of match[1].split('\n')) {
+        const colon = line.indexOf(':');
+        if (colon === -1)
+            continue;
+        const key = line.slice(0, colon).trim();
+        const value = line.slice(colon + 1).trim();
+        if (key)
+            meta[key] = value;
+    }
+    return { meta, body: match[2] };
+}
+/**
+ * Scan one or more skill directories and return a de-duplicated skill index.
+ * Directories are processed in order — first occurrence of a name wins,
+ * so workspace-level skills override app-bundled skills.
+ */
+export function loadSkillIndex(skillsDirs) {
+    const skills = [];
+    const seen = new Set();
+    for (const dir of skillsDirs) {
+        if (!existsSync(dir))
+            continue;
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.startsWith('.'))
+                continue;
+            const entryPath = join(dir, entry);
+            // Directory skill: subdirectory containing skill.md
+            const skillMd = join(entryPath, 'skill.md');
+            if (existsSync(skillMd)) {
+                try {
+                    const content = readFileSync(skillMd, 'utf-8');
+                    const { meta } = parseFrontmatter(content);
+                    const name = meta.name || entry;
+                    if (!seen.has(name)) {
+                        seen.add(name);
+                        skills.push({
+                            name,
+                            description: meta.description || '',
+                            loading: meta.loading === 'eager' ? 'eager' : 'on-demand',
+                            dir: entryPath,
+                            entrypoint: skillMd,
+                            isDirectory: true,
+                        });
+                    }
+                }
+                catch {
+                    // skip malformed skill
+                }
+                continue;
+            }
+            // Single-file skill: top-level .md file with valid frontmatter
+            if (extname(entry) === '.md') {
+                try {
+                    const content = readFileSync(entryPath, 'utf-8');
+                    const { meta } = parseFrontmatter(content);
+                    // Must have at least name or description to be a skill
+                    if (!meta.name && !meta.description)
+                        continue;
+                    const name = meta.name || basename(entry, '.md');
+                    if (!seen.has(name)) {
+                        seen.add(name);
+                        skills.push({
+                            name,
+                            description: meta.description || '',
+                            loading: meta.loading === 'eager' ? 'eager' : 'on-demand',
+                            dir,
+                            entrypoint: entryPath,
+                            isDirectory: false,
+                        });
+                    }
+                }
+                catch {
+                    // skip
+                }
+            }
+        }
+    }
+    return skills;
+}
+/**
+ * Load the full content of a skill's entrypoint or a named sub-file.
+ * Sanitises the file parameter to prevent path traversal.
+ */
+export function loadSkillContent(meta, file) {
+    if (file) {
+        if (!meta.isDirectory) {
+            return `Error: skill "${meta.name}" is a single-file skill with no sub-files.`;
+        }
+        // Allow only simple filenames — no slashes, no dots at start
+        const safeName = file.replace(/[^a-zA-Z0-9._-]/g, '');
+        if (!safeName || safeName.startsWith('.')) {
+            return `Error: invalid sub-file name "${file}".`;
+        }
+        const filePath = join(meta.dir, safeName);
+        if (!existsSync(filePath)) {
+            return `Error: sub-file "${safeName}" not found in skill "${meta.name}".`;
+        }
+        return readFileSync(filePath, 'utf-8');
+    }
+    return readFileSync(meta.entrypoint, 'utf-8');
+}
+/**
+ * Build the skill index section to append to the system prompt.
+ * Eager skills are inlined separately; this lists only on-demand skills.
+ */
+export function buildSkillIndexPrompt(skills) {
+    const onDemand = skills.filter(s => s.loading === 'on-demand');
+    if (onDemand.length === 0)
+        return '';
+    const lines = [
+        '## Available Skills',
+        '',
+        'Call `load_skill` to load domain-specific guidance when it is relevant to the current task.',
+        '',
+        ...onDemand.map(s => `- **${s.name}** — ${s.description}`),
+    ];
+    return lines.join('\n');
+}
+/**
+ * Return the full content of all eager skills, to be injected directly
+ * into the system prompt at startup.
+ */
+export function loadEagerSkills(skills) {
+    return skills
+        .filter(s => s.loading === 'eager')
+        .map(s => loadSkillContent(s))
+        .join('\n\n---\n\n');
+}
+//# sourceMappingURL=skill-loader.js.map

package/dist/agent/skill-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-loader.js","sourceRoot":"","sources":["../../src/agent/skill-loader.ts"],"names":[],"mappings":"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"}

package/dist/agent/skills/{bundled/enrich-entities.md → enrich-entities.md}

@@ -8,6 +8,18 @@ loading: eager
 
 When you discover incomplete entities (missing recommended fields), proactively suggest enrichment using contextual inference.
 
+## Batch Enrichment (automated)
+
+For bulk enrichment of entities with low completeness scores, use the `enrich_run` tool:
+
+1. `enrich_run({ dryRun: true })` — preview what would be enriched
+2. Present summary to user, get confirmation
+3. `enrich_run()` — run enrichment (writes in-place, no git commit)
+4. "Review changes with `studiograph review`, then commit with `studiograph commit`"
+5. `workspace_commit({ messagePrefix: "enrich" })` — or let user commit via CLI
+
+Use `enrich_abort` to discard all changes if the results aren't satisfactory.
+
 ## When to Enrich
 
 **Proactive discovery:**

package/dist/agent/skills/entity-schema.md

@@ -0,0 +1,502 @@
+---
+name: entity-schema
+description: Complete entity type reference — fields, repo groupings, status enums, file layout, and example frontmatter
+loading: on-demand
+---
+
+# Entity Schema Reference
+
+Use this reference when creating, validating, scaffolding, or mapping entities. All entities are Markdown files with YAML frontmatter stored in `{repo}/{entity_id}/main.md` (entity-folder layout).
+
+## Repo Types
+
+| Repo Type | Purpose | Typical Entity Types |
+|-----------|---------|---------------------|
+| `project` | One per client/initiative | project, meeting, decision, task, brief, artifact, deliverable |
+| `function` | Business operations | proposal, contract, person, client, financial-plan, deal, vendor, role |
+| `shared-resource` | Team knowledge | template, process, standard, reference, technique, practice-area, case-study |
+
+Custom types are also supported via `schema_extensions` in workspace config.
+
+## Base Fields (all entities)
+
+Every entity inherits these fields. They are auto-populated by the system on create/update.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `entity_type` | string | Yes | The entity type identifier |
+| `entity_id` | string (kebab-case) | Yes | Unique ID: lowercase, numbers, hyphens, underscores |
+| `created_at` | datetime | Yes | ISO 8601 |
+| `updated_at` | datetime | Yes | ISO 8601 |
+| `created_by` | string | Yes | Username |
+| `updated_by` | string | Yes | Username |
+| `visibility` | enum | No | `public` \| `team` (default) \| `admin` \| `restricted` |
+| `restricted_to` | string[] | No | User IDs (when visibility=restricted) |
+| `sensitive_fields` | string[] | No | Fields containing sensitive data |
+| `tags` | string[] | No | Categorization tags |
+
+Schemas use `.passthrough()` — custom fields beyond the schema are preserved.
+
+## Wikilinks
+
+Cross-entity references use `[[entity-id]]` wikilink syntax in string or string[] fields. Fields named `related_*`, `contacts`, `team`, `attendees`, `proposals`, `artifacts`, `deliverables` typically hold wikilinks.
+
+---
+
+## Project Repo Entities
+
+### project
+
+A client engagement or internal initiative.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Project name |
+| `client` | string | No | Client name or wikilink |
+| `website_url` | url | No | Project website |
+| `start_date` | string | No | ISO 8601 or human-readable |
+| `end_date` | string | No | Project end date |
+| `target_completion` | string | No | Target completion date |
+| `year_released` | number | No | Year released |
+| `status` | enum | No | `planning` \| `scoping` \| `active` \| `on-hold` \| `completed` \| `archived` |
+| `related_projects` | string[] | No | Related project wikilinks |
+| `related_areas` | string[] | No | Practice area wikilinks |
+| `team` | string[] | No | Team member wikilinks |
+| `deliverables` | string[] | No | Deliverable wikilinks |
+| `deal` | string | No | Originating deal wikilink |
+
+### meeting
+
+Meeting notes, decisions, and action items.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Meeting name/subject |
+| `date` | string | No | Meeting date |
+| `attendees` | string[] | No | Attendee names or wikilinks |
+| `related_projects` | string[] | No | Project wikilinks |
+| `related_organizations` | string[] | No | Organization wikilinks |
+| `related_areas` | string[] | No | Practice area wikilinks |
+| `agenda` | string | No | Agenda (markdown) |
+| `notes` | string | No | Notes (markdown) |
+| `action_items` | string[] | No | Action items |
+| `summary` | string | No | Meeting summary |
+
+### decision
+
+Structured decision records (ADR-style). ID format: `DEC-YYYY-NNN`.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | Yes | Format: DEC-YYYY-NNN |
+| `title` | string | Yes | Decision title |
+| `date` | string | Yes | Decision date |
+| `status` | enum | No | `proposed` (default) \| `accepted` \| `rejected` \| `deprecated` \| `superseded` |
+| `decision_makers` | string[] | No | Who decided |
+| `stakeholders` | string[] | No | Who's affected |
+| `related_decisions` | string[] | No | Related decision wikilinks |
+| `supersedes` | string | No | Decision this replaces |
+| `superseded_by` | string | No | Decision that replaces this |
+| `context` | string | No | Background |
+| `alternatives` | string | No | Alternatives considered |
+| `decision` | string | No | The actual decision |
+| `rationale` | string | No | Why chosen |
+| `consequences` | string | No | Outcomes and risks |
+| `enables` | string[] | No | Decisions this enables |
+
+### task
+
+Lightweight action items and to-dos.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Task name |
+| `assignee` | string | No | Person wikilink |
+| `due_date` | string | No | Due date |
+| `status` | enum | No | `open` (default) \| `in-progress` \| `done` \| `cancelled` |
+| `priority` | enum | No | `low` \| `medium` \| `high` \| `urgent` |
+| `project` | string | No | Project wikilink |
+| `deliverable` | string | No | Deliverable wikilink |
+| `related_meeting` | string | No | Meeting wikilink |
+| `description` | string | No | Detailed description |
+
+### brief
+
+Project briefs and requirements documents.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `project_name` | string | Yes | Project name |
+| `client` | string | No | Client wikilink |
+| `start_date` | string | No | Start date |
+| `target_completion` | string | No | Target completion |
+| `status` | enum | No | `planning` (default) \| `approved` \| `in-progress` \| `completed` |
+| `objectives` | string[] | No | Project objectives |
+| `target_users` | string | No | Target users/audience |
+| `success_criteria` | string[] | No | Success criteria |
+| `constraints` | string | No | Constraints |
+| `stakeholders` | string[] | No | Stakeholder wikilinks |
+| `deliverables` | string[] | No | Expected deliverables |
+| `related_projects` | string[] | No | Related project wikilinks |
+
+### artifact
+
+Individual project outputs (files, designs, prototypes).
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Artifact name |
+| `type` | string | No | e.g. presentation, prototype, report, design-file |
+| `project` | string | No | Project wikilink |
+| `deliverable` | string | No | Parent deliverable wikilink |
+| `date_created` | string | No | Creation date |
+| `description` | string | No | Description |
+| `url` | string | No | URL or file path |
+| `version` | string | No | Version number |
+
+### deliverable
+
+Scoped, contractual output promised to a client. Higher-level than artifacts: a deliverable (e.g. "Brand Identity System") contains artifacts (logo SVG, style guide PDF).
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Deliverable name |
+| `project` | string | No | Project wikilink |
+| `proposal` | string | No | Originating proposal wikilink |
+| `contract` | string | No | Formalizing contract wikilink |
+| `artifacts` | string[] | No | Component artifact wikilinks |
+| `status` | enum | No | `planned` (default) \| `in-progress` \| `delivered` \| `accepted` \| `rejected` |
+| `due_date` | string | No | Due date |
+| `delivered_date` | string | No | Actual delivery date |
+| `description` | string | No | What this comprises |
+
+---
+
+## Function Repo Entities
+
+### proposal
+
+Client proposals and SOWs.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Proposal name |
+| `client` | string | No | Client wikilink |
+| `project_name` | string | No | Project name |
+| `date` | string | No | Proposal date |
+| `version` | string | No | e.g. v1, v2 |
+| `status` | enum | No | `draft` (default) \| `sent` \| `accepted` \| `rejected` \| `negotiating` |
+| `deliverables` | string[] | No | Proposed deliverables |
+| `phases` | string | No | Project phases (markdown) |
+| `team` | string[] | No | Proposed team members |
+| `schedule` | string | No | Proposed schedule |
+| `fees` | string | No | Fee structure |
+| `payment_terms` | string | No | Payment terms |
+
+### contract
+
+SOWs, MSAs, NDAs.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Contract name |
+| `type` | enum | No | `sow` \| `msa` \| `nda` \| `other` |
+| `client` | string | No | Client wikilink |
+| `project` | string | No | Project wikilink |
+| `date_signed` | string | No | Signature date |
+| `start_date` | string | No | Start date |
+| `end_date` | string | No | End date |
+| `status` | enum | No | `draft` (default) \| `pending` \| `signed` \| `completed` \| `terminated` |
+| `value` | string | No | Contract value |
+| `payment_terms` | string | No | Payment terms |
+
+### person
+
+Team members, clients, contacts.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Full name |
+| `role` | string | No | Role or title |
+| `status` | enum | No | `current` \| `former` \| `contractor` \| `client` \| `partner` |
+| `email` | string | No | Email address |
+| `location` | string | No | Location |
+| `organization` | string | No | Organization wikilink |
+| `years_experience` | number | No | Years of experience |
+| `bio` | string | No | Biography (markdown) |
+| `projects` | string[] | No | Project wikilinks |
+| `reports_to` | string | No | Manager or role wikilink |
+| `department` | string | No | e.g. Creative Technology, Design |
+
+### client
+
+Client organizations.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Client name |
+| `type` | enum | No | `corporate` \| `nonprofit` \| `government` \| `startup` \| `agency` \| `other` |
+| `status` | enum | No | `active` (default) \| `inactive` \| `prospect` \| `former` |
+| `industry` | string | No | Industry sector |
+| `website` | url | No | Website URL |
+| `location` | string | No | Primary location |
+| `size` | enum | No | `small` \| `medium` \| `large` \| `enterprise` |
+| `contacts` | string[] | No | Person wikilinks |
+| `projects` | string[] | No | Project wikilinks |
+| `relationship_start` | string | No | Relationship start date |
+| `notes` | string | No | Additional notes (markdown) |
+
+### financial-plan
+
+Budgets, rates, forecasts.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Plan name |
+| `type` | enum | No | `budget` \| `forecast` \| `rates` \| `compensation` |
+| `period` | string | No | e.g. Q1 2026, FY2026 |
+| `project` | string | No | Project wikilink |
+| `amounts` | string | No | Financial amounts (markdown table) |
+
+### deal
+
+Pre-project sales opportunity.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Deal name |
+| `client` | string | No | Client wikilink |
+| `contacts` | string[] | No | Contact person wikilinks |
+| `stage` | enum | No | `scoping` (default) \| `proposal` \| `negotiating` \| `won` \| `lost` |
+| `deal_value` | number | No | Estimated value (USD) |
+| `probability` | number (0-100) | No | Win probability |
+| `expected_close` | string | No | Expected close date |
+| `source` | enum | No | `referral` \| `inbound` \| `outbound` \| `repeat` \| `partner` \| `other` |
+| `proposals` | string[] | No | Proposal wikilinks |
+| `project` | string | No | Resulting project wikilink (once won) |
+| `lost_reason` | string | No | Why lost |
+
+### vendor
+
+External suppliers, freelancers, partners.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Vendor name |
+| `type` | enum | No | `freelancer` \| `agency` \| `supplier` \| `platform` \| `partner` \| `other` |
+| `status` | enum | No | `active` (default) \| `inactive` \| `preferred` |
+| `contact_name` | string | No | Primary contact |
+| `email` | string | No | Contact email |
+| `website` | url | No | Website URL |
+| `services` | string[] | No | Services provided |
+| `projects` | string[] | No | Project wikilinks |
+| `notes` | string | No | Additional notes (markdown) |
+
+### role
+
+Role definitions from the firm's leveling framework. Body holds: Role Overview, Key Responsibilities, Leveling Criteria, Required Skills.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `title` | string | Yes | Role title |
+| `department` | string | No | e.g. Creative Technology, Design |
+| `level` | number | No | Level 1-5 |
+| `type` | enum | No | `staff` \| `contractor` \| `intern` |
+| `status` | enum | No | `active` (default) \| `archived` |
+| `location` | string | No | Location |
+| `reports_to` | string | No | Parent role or person wikilink |
+
+---
+
+## Shared Resource Repo Entities
+
+### template
+
+Document templates and boilerplates.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Template name |
+| `category` | string | No | e.g. proposal, brief, sow, meeting-notes |
+| `description` | string | No | Template description |
+| `template_content` | string | No | Template content (markdown) |
+| `variables` | string[] | No | Template variables e.g. `{{project_name}}` |
+
+### process
+
+Workflows, SOPs, and methodologies.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Process name |
+| `description` | string | No | Process description |
+| `steps` | string | No | Process steps (markdown) |
+| `related_areas` | string[] | No | Practice area wikilinks |
+| `related_templates` | string[] | No | Template wikilinks |
+| `owner` | string | No | Responsible person/team wikilink |
+| `review_cycle` | enum | No | `monthly` \| `quarterly` \| `annual` \| `as-needed` |
+
+### standard
+
+Guidelines and best practices.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Standard name |
+| `category` | string | No | e.g. accessibility, design-principles, code-standards |
+| `description` | string | No | Standard description |
+| `guidelines` | string | No | Guidelines (markdown) |
+| `examples` | string[] | No | Example wikilinks |
+
+### reference
+
+External references and inspirations.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Reference name |
+| `type` | enum | No | `article` \| `video` \| `visualization` \| `website` \| `research` \| `podcast` \| `project` \| `tool` |
+| `date` | string | No | Publication date |
+| `source` | string | No | Source/author |
+| `link` | string | No | URL |
+| `related_projects` | string[] | No | Project wikilinks |
+| `related_people` | string[] | No | People wikilinks |
+| `related_areas` | string[] | No | Practice area wikilinks |
+| `description` | string | No | Description |
+
+### technique
+
+Methods and patterns.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Technique name |
+| `category` | string | No | e.g. visualization, interaction-pattern |
+| `description` | string | No | Description |
+| `difficulty` | enum | No | `beginner` \| `intermediate` \| `advanced` |
+| `related_frameworks` | string[] | No | Framework wikilinks |
+| `examples` | string[] | No | Example wikilinks |
+
+### practice-area
+
+Firm capabilities and disciplines.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Practice area name |
+| `description` | string | No | Overview of the discipline |
+| `capabilities` | string[] | No | Specific service offerings |
+| `related_case_studies` | string[] | No | Case study wikilinks |
+| `related_projects` | string[] | No | Project wikilinks |
+
+### case-study
+
+Portfolio narratives for completed projects. Body holds: Objective, Solution, Outcome, Team, Press, Awards.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `title` | string | Yes | Case study title |
+| `client` | string | No | Client wikilink |
+| `year` | number | No | Year of the project |
+| `practice_areas` | string[] | No | Practice area wikilinks |
+| `sectors` | string[] | No | Industry tags |
+| `website_url` | url | No | Project website URL |
+| `description` | string | No | Short description / meta |
+
+---
+
+## Special Entity Types
+
+### dataset
+
+Structured tabular data with CSV body.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Dataset name |
+| `schema` | ColumnDefinition[] | Yes | Column definitions (min 1) |
+
+Each column: `{ name, type: "string"|"number"|"boolean"|"date", required?, description? }`
+
+### deck
+
+Presentation deck (Schema Slides app plugin). Body is slide markdown.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `title` | string | Yes | Deck title |
+| `client` | string | No | Client |
+| `date` | string | Yes | Date |
+| `phase` | string | No | Phase |
+| `theme` | enum | No | `dark` (default) \| `light` |
+| `status` | enum | No | `draft` (default) \| `review` \| `approved` |
+| `related_project` | string | No | Project wikilink |
+| `related_client` | string | No | Client wikilink |
+
+---
+
+## File Layout
+
+Entities use the **entity-folder** layout:
+
+```
+{repo}/
+  {entity_id}/
+    main.md          # Sentinel file (frontmatter + body)
+    notes/           # Optional sub-content
+    artifacts/       # Optional attachments
+```
+
+- `entity_id` must be kebab-case: `acme-website-redesign`
+- The folder name IS the entity_id
+- `main.md` is the sentinel — its presence defines the entity
+- Sub-content (notes, artifacts) lives alongside main.md
+
+## Example Frontmatter
+
+```yaml
+---
+entity_type: project
+entity_id: acme-website-redesign
+name: Acme Website Redesign
+client: "[[acme-corp]]"
+start_date: "2026-01-15"
+end_date: "2026-06-30"
+status: active
+related_areas:
+  - "[[ux-design]]"
+  - "[[design-engineering]]"
+team:
+  - "[[christian-schmidt]]"
+  - "[[kenton-powell]]"
+tags:
+  - website
+  - redesign
+created_at: "2026-01-15T00:00:00Z"
+updated_at: "2026-02-20T00:00:00Z"
+created_by: christian-schmidt
+updated_by: christian-schmidt
+---
+
+# Acme Website Redesign
+
+Project content goes here. Use [[wikilinks]] to reference other entities.
+```
+
+## Scaffolding Repos
+
+When scaffolding a workspace (Obsidian vault, Google Drive, or file system), create one directory per repo and seed each with README.md or an empty entity folder. Recommended repo groupings:
+
+| Repo Name | Repo Type | Entity Types |
+|-----------|-----------|-------------|
+| `projects` | project | project, brief, deliverable, artifact |
+| `meetings` | project | meeting, decision |
+| `clients` | function | client, vendor, deal |
+| `people` | function | person, role |
+| `proposals` | function | proposal, contract |
+| `finance` | function | financial-plan |
+| `case-studies` | shared-resource | case-study |
+| `processes` | shared-resource | process, standard |
+| `practice-areas` | shared-resource | practice-area, technique |
+| `resources` | shared-resource | reference, template |
+| `tasks` | project | task |