studiograph 1.3.48-next.13 → 1.3.48-next.131

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

@@ -1,112 +1,71 @@
 ---
 name: entity-schema
-description: Complete entity type reference — fields, repo groupings, status enums, file layout, and example frontmatter
+description: Field reference for commonly-used canonical entity types — required/optional fields, status enums, file layout, frontmatter
 loading: on-demand
 ---
 
-# Entity Schema Reference
+# Entry 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).
+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).
 
-## Repo Types
+Studiograph has 20 canonical entity types. This file covers the most common ones with their key fields. For any type not covered here (e.g. `decision`, `deliverable`, `process`, `guideline`, `case-study`, `publication`, `deal`, `role`, `practice-area`, `skill`), call `get_entity_schema` to get the authoritative schema. Workspaces may also define custom types via `schema_extensions` in their workspace config.
 
-| 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 |
+## Base Fields (all entries)
 
-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.
+Every entry inherits these fields. Most are auto-populated by the system on create/update.
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `entity_type` | string | Yes | The entity type identifier |
+| `entity_type` | string | Yes | The entry 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 (Title Case, except acronyms which stay uppercase: e.g., "AI", "UI Design", "B2B", "Dashboard") |
+| `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 |
+| `tags` | string[] | No | Categorization tags (Title Case, except acronyms which stay uppercase: "AI", "UI Design", "B2B") |
 
 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.
+Cross-entry references use `[[entity-id]]` wikilink syntax in string or string[] fields. Fields named `related_*`, `attendees`, `team`, `assignee`, `organization`, `project` typically hold wikilinks.
 
 ---
 
-## Project Repo Entities
+## note
 
-### project
-
-A client engagement or internal initiative.
+Freeform thinking, research, scratch notes, brainstorms, drafts.
 
 | 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 |
+| `name` | string | Yes | Note name |
+| `related_projects` | string[] | No | Project wikilinks |
+| `related_people` | string[] | No | Person wikilinks |
+
+Prefer `note` for freeform thinking. For anything that has a more specific canonical type (decision, deck, deliverable, publication, case-study, process, guideline, reference, document), use that type instead of collapsing it into a note.
 
-### meeting
+## meeting
 
-Meeting notes, decisions, and action items.
+Meetings, calls, workshops — with attendees, agenda, notes, action items.
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `name` | string | Yes | Meeting name/subject |
-| `date` | string | No | Meeting date |
-| `attendees` | string[] | No | Attendee names or wikilinks |
+| `date` | string | No | Meeting date (ISO or human-readable) |
+| `attendees` | string[] | No | Person 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
+The `date` field must reflect when the meeting actually occurred, not when the entry was captured.
 
-Structured decision records (ADR-style). ID format: `DEC-YYYY-NNN`.
+## task
 
-| 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.
+Action items and to-dos.
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
@@ -116,103 +75,53 @@ Lightweight action items and to-dos.
 | `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 |
+| `related_meeting` | string | No | Meeting wikilink (if task came from a meeting) |
 | `description` | string | No | Detailed description |
 
-### brief
+Use `assignee` (schema field). Never invent `assigned_to`.
 
-Project briefs and requirements documents.
+## document
 
-| 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).
+Any authored document — reports, proposals, briefs, memos, templates, financial plans.
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `name` | string | Yes | Artifact name |
-| `type` | string | No | e.g. presentation, prototype, report, design-file |
+| `name` | string | Yes | Document name |
+| `category` | enum | No | `proposal` \| `contract` \| `brief` \| `memo` \| `report` \| `template` \| `other` |
+| `status` | enum | No | `draft` (default) \| `review` \| `final` \| `archived` |
+| `client` | string | No | Client organization wikilink |
 | `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
+Use `document` for structured authored content whose shape doesn't warrant a dedicated canonical type. For presentations/slide decks use `deck` instead. For decisions use `decision`. For case studies use `case-study`. For processes use `process`.
+
+## deck
 
-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).
+Presentations and slide decks. Generic front-matter type independent of any slides renderer — the body holds the outline/narrative.
 
 | 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 |
-
----
+| `name` | string | Yes | Deck name |
+| `audience` | string | No | Intended audience (client, team, board) |
+| `status` | enum | No | `draft` (default) \| `review` \| `final` \| `archived` |
+| `presented_at` | string | No | Date presented or scheduled to present |
 
-## Function Repo Entities
+## dataset
 
-### proposal
-
-Client proposals and SOWs.
+Structured tabular data with typed columns. The markdown body holds CSV rows; the frontmatter `schema` defines column types.
 
 | 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.
+| `name` | string | Yes | Dataset name |
+| `schema` | ColumnDefinition[] | Yes | Column definitions (min 1) |
+| `description` | string | No | What the data represents |
 
-| 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 |
+Each column in `schema` is `{ name, type: "string"|"number"|"boolean"|"date", required?, description? }`.
 
-### person
+Datasets are created from CSV uploads (schema inferred automatically) or manually. Use `query_dataset` to filter rows and `append_rows` to add data.
 
-Team members, clients, contacts.
+## person
+
+Team members, client contacts, any individual.
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
@@ -222,210 +131,59 @@ Team members, clients, contacts.
 | `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
+The `name` must be the full human name as it appears in the source. If only a first name is given, use "First (Organization)" (e.g., "Andrew (Simpson Thacher)") rather than truncating.
 
-Client organizations.
+## organization
 
-| 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.
+Clients, vendors, partners, prospects, industry bodies.
 
 | 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 |
+| `name` | string | Yes | Organization name |
+| `category` | enum | No | `client` \| `vendor` \| `partner` \| `prospect` \| `industry-body` \| `other` |
+| `status` | enum | No | `active` (default) \| `inactive` \| `former` |
+| `industry` | string | No | Industry sector |
 | `website` | url | No | Website URL |
-| `services` | string[] | No | Services provided |
-| `projects` | string[] | No | Project wikilinks |
-| `notes` | string | No | Additional notes (markdown) |
 
-### role
+## project
 
-Role definitions from the firm's leveling framework. Body holds: Role Overview, Key Responsibilities, Leveling Criteria, Required Skills.
+Client engagements and internal initiatives.
 
 | 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 |
+| `name` | string | Yes | Project name |
+| `client` | string | No | Client organization wikilink |
+| `website_url` | url | No | Project website |
+| `start_date` | string | No | ISO 8601 |
+| `end_date` | string | No | End date |
+| `status` | enum | No | `planning` \| `scoping` \| `active` \| `on-hold` \| `completed` \| `archived` |
+| `team` | string[] | No | Person wikilinks |
+| `related_projects` | string[] | No | Related project wikilinks |
 
-### reference
+## reference
 
-External references and inspirations.
+External resources and inspiration.
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `name` | string | Yes | Reference name |
-| `type` | enum | No | `article` \| `video` \| `visualization` \| `website` \| `research` \| `podcast` \| `project` \| `tool` |
+| `type` | enum | No | `article` \| `video` \| `tool` \| `technique` \| `framework` \| `website` |
 | `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 |
+| `related_people` | string[] | No | Person 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? }`
-
 ---
 
 ## 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 +191,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
 
@@ -448,9 +205,6 @@ 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]]"
@@ -465,23 +219,5 @@ 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 |