studiograph 1.3.47 → 1.3.48-beta.1

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

@@ -1,431 +1,98 @@
 ---
 name: entity-schema
-description: Complete entity type reference — fields, repo groupings, status enums, file layout, and example frontmatter
+description: Field reference for canonical entity types — file layout, base fields, wikilinks. Enum values come from get_entity_schema.
 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.
+# Entry Schema Reference
+
+Use this reference when creating, validating, or mapping entries. All entries are Markdown files with YAML frontmatter stored in `{folder}/{entity_id}/main.md` (entity-folder layout).
+
+Studiograph has 16 canonical entity types (15 user-facing + 1 system). The full per-type field list — including enum values, defaults, and descriptions — lives in `src/core/validation.ts` (`ENTITY_SCHEMAS`). **Do not memorize field shapes from this document.** Call `get_entity_schema(entityType)` to fetch the authoritative schema before writing. Workspaces may also define custom types via `schema_extensions` in their workspace config; those types are returned by `get_entity_schema` too.
+
+## When to call `get_entity_schema`
+
+- Before the first create/update of a given entity type in a conversation.
+- After any error mentioning an unknown enum value, a missing field, or a type mismatch.
+- Whenever you're about to write a field name that hints at an enum (`stage`, `status`, `category`, `priority`, `audience`, `source`, `type`) and you don't have the current list in this turn.
+
+The response shape:
+
+```json
+{
+  "success": true,
+  "entityType": "deal",
+  "fields": {
+    "name": { "type": "string", "optional": false, "description": "Deal name is required" },
+    "stage": {
+      "type": "enum",
+      "optional": true,
+      "description": "Pipeline stage",
+      "enum": ["qualification", "scoping", "proposal", "negotiation", "pending-signature", "won", "lost"],
+      "default": "qualification"
+    },
+    "deal_value": { "type": "number", "optional": true, "description": "Estimated deal value" },
+    "services": {
+      "type": "string[]",
+      "optional": true,
+      "description": "Service entities this project includes (wikilinks)",
+      "itemType": "string"
+    }
+  }
+}
+```
 
-| 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 |
+Use `enum` to know what's allowed, `default` to know what you'll get if you omit the field, and `description` to disambiguate similar field names.
 
-### practice-area
+## Base Fields (all entries)
 
-Firm capabilities and disciplines.
+Every entry inherits these fields. Most are auto-populated by the system on create/update — do not pass them yourself.
 
 | 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 |
+| `entity_type` | string | Yes | The entry type identifier (passed as the `entityType` parameter, not in `data`) |
+| `entity_id` | string (kebab-case) | Yes | Unique ID: lowercase letters, numbers, hyphens, underscores |
+| `created_at` | datetime | Yes | ISO 8601 (auto) |
+| `updated_at` | datetime | Yes | ISO 8601 (auto) |
+| `created_by` | string | Yes | Username (auto) |
+| `updated_by` | string | Yes | Username (auto) |
+| `date` | string | No | Human-friendly date (event date, project start, etc.) |
+| `tags` | string[] | No | Categorization tags (Title Case, except acronyms which stay uppercase: "AI", "UI Design", "B2B") |
 
-### case-study
+Schemas use `.passthrough()` — custom fields beyond the schema are preserved on disk.
 
-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 |
+## Canonical Entity Types
 
----
+The 16 canonical types are grouped into five categories. For each, call `get_entity_schema` to see required fields, enums, and defaults.
 
-## Special Entity Types
+**CRM:** `person`, `organization`, `position`, `deal`
+**PM:** `project`, `event`, `task`, `deliverable`
+**KM (authored):** `document`, `deck`, `publication`, `case-study`, `service`, `skill`
+**Capture:** `note`, `reference`
+**System:** `asset` (hidden from New Entry picker — created via upload), `comment` (virtual, SQLite-backed)
 
-### dataset
+Quick notes on common types:
 
-Structured tabular data with CSV body.
+- **person** — `name` is required; `role` is free-text (distinct from the `position` entity type, which is a job spec).
+- **organization** — clients/vendors/partners/prospects.
+- **deal** — pre-project pipeline opportunity. `stage` defaults to the earliest pipeline value.
+- **event** — any scheduled gathering (meeting, call, workshop, review, presentation, conference). Body holds Summary / Notes / Action Items.
+- **task** — `assignee` (not `assigned_to`), free-text `phase`.
+- **note** — freeform capture. Decisions land here as plain notes.
+- **deck** — slide decks. Has a dedicated renderer; pattern-matches on `entity_type === 'deck'`.
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `name` | string | Yes | Dataset name |
-| `schema` | ColumnDefinition[] | Yes | Column definitions (min 1) |
+For anything more specific (which enum values are valid, what's required, what defaults apply), call `get_entity_schema`.
 
-Each column: `{ name, type: "string"|"number"|"boolean"|"date", required?, description? }`
+## Wikilinks
 
----
+Cross-entry references use `[[entity-id]]` wikilink syntax in string or string[] fields. Fields named `attendees`, `team`, `assignee`, `organization`, `client`, `services`, `depends_on`, `enables`, `project` typically hold wikilinks. The schema returns `string` / `string[]` for these — the wikilink convention is semantic, not enforced at the type level.
 
 ## File Layout
 
-Entities use the **entity-folder** layout:
+Entries use the **entity-folder** layout:
 
 ```
-{repo}/
+{folder}/
   {entity_id}/
     main.md          # Sentinel file (frontmatter + body)
     notes/           # Optional sub-content
@@ -433,9 +100,8 @@ Entities use the **entity-folder** layout:
 ```
 
 - `entity_id` must be kebab-case: `acme-website-redesign`
-- The folder name IS the entity_id
+- 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
 
@@ -446,17 +112,11 @@ 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:
-  - "[[alice-smith]]"
-  - "[[jamie-torres]]"
+date: "2026-06-30"        # a project's `date` is its end date
+status: in-progress
 tags:
-  - website
-  - redesign
+  - Website
+  - Redesign
 created_at: "2026-01-15T00:00:00Z"
 updated_at: "2026-02-20T00:00:00Z"
 created_by: alice-smith
@@ -465,23 +125,7 @@ updated_by: alice-smith
 
 # Acme Website Redesign
 
-Project content goes here. Use [[wikilinks]] to reference other entities.
+Project content goes here. Use [[wikilinks]] to reference other entries.
 ```
 
-## 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 |
+The `status` value above is illustrative — call `get_entity_schema('project')` to see the current allowed values before writing.