studiograph 1.1.3 → 1.2.0-beta.2

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 |