studiograph 1.3.47 → 1.3.48-beta.1

package/dist/core/validation.js

@@ -1,15 +1,29 @@
 /**
  * Entity validation schemas for Studiograph
  *
- * 17 built-in entity types organized into three categories:
- * - Identity (4): person, organization, role, practice-area
- * - Universal (10): project, meeting, decision, task, document, dataset, reference, note, deliverable, publication
- * - Knowledge (3): process, standard, case-study
+ * 17 canonical entity types post-redesign:
+ * - CRM (4): person, organization, position, deal
+ * - PM (4): project, event, task, deliverable
+ * - KM authored (6): document, deck, publication, case-study, service, skill
+ * - Capture (3): note, reference, dataset
+ * - System (1): asset
  *
- * App plugins register additional types at runtime via SchemaRegistry.
- * Teams can define custom types via schema_extensions in workspace config.
+ * "An object earns first-class entity status only if it earns its own view
+ * behavior across the six primary views (List, Gallery, Kanban, Calendar,
+ * Timeline, Graph). Objects that are mostly useful because they're attached
+ * to something else become categories, fields, or inline blocks — not types."
+ *
+ * Workspaces can define additional custom types via schema_extensions.
  */
 import { z } from 'zod';
+function dateField(role, label, description) {
+    return z
+        .string()
+        .date()
+        .optional()
+        .describe(description ?? label)
+        .meta({ dateRole: role, label });
+}
 /**
  * Base entity schema - all entities have these fields
  */
@@ -22,328 +36,420 @@ export const EntityBaseSchema = z.object({
     updated_at: z.string().datetime('Invalid datetime format'),
     created_by: z.string().min(1, 'Created by is required'),
     updated_by: z.string().min(1, 'Updated by is required'),
-    date: z.string().optional().describe('Human-friendly date (e.g., meeting date, project start, note taken)'),
+    date: dateField('primary', 'Date', "The entity's primary date (YYYY-MM-DD)"),
     tags: z.array(z.string())
         .optional()
         .describe('Tags for categorization'),
 }).passthrough(); // Allow custom fields beyond the base schema
 // ══════════════════════════════════════════════════════════════════════════════
-// IDENTITY ENTITIES — people, organizations, roles, practice areas
+// CRM — people, organizations, positions, deals
 // ══════════════════════════════════════════════════════════════════════════════
 /**
- * Person — team members, client contacts, any individual
+ * Person — team members, client contacts, any individual.
+ *
+ * `category` and `status` are split: category is the relationship type
+ * (employee/contractor/client/partner) and status is whether that
+ * relationship is current or historical. Mirrors organization.
  */
 export const PersonSchema = EntityBaseSchema.extend({
     entity_type: z.literal('person'),
     name: z.string().min(1, 'Person name is required'),
-    role: z.string().optional().describe('Role or title'),
-    status: z.enum(['current', 'former', 'contractor', 'client', 'partner'])
+    role: z.string().optional().describe('Free-text title (distinct from `position` entity)'),
+    category: z.enum(['employee', 'contractor', 'client', 'partner', 'other'])
         .optional()
-        .describe('Relationship status'),
+        .describe('Relationship category'),
+    status: z.enum(['current', 'former'])
+        .optional()
+        .describe('Whether the relationship is current or historical'),
     email: z.string().optional().describe('Email address'),
     location: z.string().optional().describe('Location'),
     organization: z.string().optional().describe('Organization wikilink'),
-    bio: z.string().optional().describe('Biography (markdown)'),
-    projects: z.array(z.string()).optional().describe('Related project wikilinks'),
-    reports_to: z.string().optional().describe('Manager or role wikilink'),
-    department: z.string().optional().describe('Department'),
+    // Bridge to the auth.db user account this person represents. Scalar handle
+    // string (not a wikilink): users are out-of-graph identities. Workspace-
+    // unique — write-path enforcement lives in user-person-bridge.ts. Optional
+    // because person entities can exist without a corresponding user
+    // (contractors, client contacts, anyone in the org chart who doesn't log
+    // in). Empty string is the "cleared" form — graph.create seeds optional
+    // string fields to "" on new entities, and unlink writes "" as well, so
+    // the regex must accept it explicitly.
+    user_handle: z.string()
+        // Empty (cleared) OR a kebab-case handle: leading alnum, alnum/hyphen
+        // body, alnum tail, no doubled hyphens. Mirrors what auth's
+        // slugifyHandle + allocateHandle can actually emit — accepting
+        // `foo-` or `foo--bar` here would let a hand-edit drift outside what
+        // findUserByHandle can match.
+        .regex(/^(|[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9]))*)$/, 'user_handle must match the auth handle format (lowercase, single hyphens between alnums, alnum endpoints)')
+        .optional()
+        .describe('Auth handle of the user this person represents'),
 });
 /**
- * Organization — clients, vendors, partners, prospects, industry bodies
- * Replaces the former separate client and vendor types.
+ * Organization — clients, vendors, partners, prospects, professional
+ * associations.
  */
 export const OrganizationSchema = EntityBaseSchema.extend({
     entity_type: z.literal('organization'),
     name: z.string().min(1, 'Organization name is required'),
-    category: z.enum(['client', 'vendor', 'partner', 'prospect', 'industry-body', 'other'])
+    category: z.enum(['client', 'vendor', 'partner', 'prospect', 'professional-association', 'other'])
         .optional()
         .describe('Relationship category'),
-    status: z.enum(['active', 'inactive', 'prospect', 'former'])
+    status: z.enum(['active', 'dormant', 'former'])
         .default('active')
-        .describe('Organization status'),
+        .describe('Organization status (`dormant` covers clients you have not worked with in a while but might again)'),
     industry: z.string().optional().describe('Industry sector'),
     website: z.string().url().optional().describe('Website URL'),
-    location: z.string().optional().describe('Primary location'),
-    size: z.enum(['small', 'medium', 'large', 'enterprise'])
-        .optional()
-        .describe('Organization size'),
-    contacts: z.array(z.string()).optional().describe('Contact person wikilinks'),
-    projects: z.array(z.string()).optional().describe('Related project wikilinks'),
-    relationship_start: z.string().optional().describe('When the relationship started'),
 });
 /**
- * Role — role definitions from the firm's leveling framework
+ * Position — a position spec or open job. Renamed from `role` to avoid
+ * collision with `person.role` (the free-text title field). Reframes from
+ * "the person's seat" to "the spec for a position."
  */
-export const RoleSchema = EntityBaseSchema.extend({
-    entity_type: z.literal('role'),
-    name: z.string().min(1, 'Role name is required'),
+export const PositionSchema = EntityBaseSchema.extend({
+    entity_type: z.literal('position'),
+    name: z.string().min(1, 'Position name is required'),
     department: z.string().optional().describe('Department'),
-    level: z.number().optional().describe('Level 1–5 from leveling framework'),
     category: z.enum(['staff', 'contractor', 'intern'])
         .optional()
         .describe('Employment category'),
-    status: z.enum(['active', 'archived'])
-        .default('active')
-        .describe('Role status'),
-    location: z.string().optional().describe('Location'),
-    reports_to: z.string().optional().describe('Parent role or person wikilink'),
+    status: z.enum(['draft', 'open', 'filled', 'closed'])
+        .default('open')
+        .describe('Position lifecycle'),
 });
 /**
- * Practice Area — firm capabilities and disciplines
+ * Deal — pre-project opportunity in the sales pipeline.
  */
-export const PracticeAreaSchema = EntityBaseSchema.extend({
-    entity_type: z.literal('practice-area'),
-    name: z.string().min(1, 'Practice area name is required'),
-    description: z.string().optional().describe('Overview of the discipline'),
-    capabilities: z.array(z.string()).optional().describe('Specific service offerings'),
-    related_case_studies: z.array(z.string()).optional().describe('Case study wikilinks'),
-    related_projects: z.array(z.string()).optional().describe('Related project wikilinks'),
+export const DealSchema = EntityBaseSchema.extend({
+    entity_type: z.literal('deal'),
+    name: z.string().min(1, 'Deal name is required'),
+    client: z.string().optional().describe('Client organization wikilink'),
+    contact: z.string().optional().describe('Primary contact person wikilink'),
+    stage: z.enum(['qualification', 'scoping', 'proposal', 'negotiation', 'pending-signature', 'won', 'lost'])
+        .default('qualification')
+        .describe('Pipeline stage'),
+    deal_value: z.number().optional().describe('Estimated deal value'),
+    start_date: dateField('start', 'Start date', 'When work on the deal began (enables Timeline rendering of duration)'),
+    date: dateField('primary', 'Close date', 'Expected close date'),
 });
 // ══════════════════════════════════════════════════════════════════════════════
-// UNIVERSAL ENTITIES — available in any repo
+// PM — project, event, task, deliverable
 // ══════════════════════════════════════════════════════════════════════════════
 /**
- * Project — a client engagement or internal initiative
+ * Project — a client engagement or internal initiative.
+ *
+ * `services` is a wikilink array to `service` entities the project includes
+ * (replaces the previous `practice_area` concept).
  */
 export const ProjectSchema = EntityBaseSchema.extend({
     entity_type: z.literal('project'),
     name: z.string().min(1, 'Project name is required'),
-    category: z.string().optional().describe('Project category (e.g., client-project, internal-initiative, event, research)'),
+    category: z.enum(['client', 'internal'])
+        .optional()
+        .describe('Project category'),
+    project_type: z.string().optional().describe('Kind of project (e.g., website, research, event, rebrand, prototype)'),
     client: z.string().optional().describe('Client organization wikilink'),
-    website_url: z.string().url().optional().describe('Project website URL'),
-    start_date: z.string().optional().describe('Project start date'),
-    end_date: z.string().optional().describe('Project end date'),
-    status: z.enum(['planning', 'scoping', 'active', 'on-hold', 'completed', 'archived'])
+    services: z.array(z.string()).optional()
+        .describe('Service entities this project includes (wikilinks)'),
+    status: z.enum(['planning', 'in-progress', 'paused', 'complete', 'archived'])
         .optional()
         .describe('Current project status'),
-    related_projects: z.array(z.string()).optional().describe('Related project wikilinks'),
-    related_areas: z.array(z.string()).optional().describe('Practice area wikilinks'),
-    team: z.array(z.string()).optional().describe('Team member wikilinks'),
-    deliverables: z.array(z.string()).optional().describe('Deliverable wikilinks'),
-    deal: z.string().optional().describe('Originating deal wikilink'),
+    start_date: dateField('start', 'Start date', 'Project start date'),
+    date: dateField('primary', 'End date', 'Project end date'),
 });
 /**
- * Meeting — any scheduled gathering
+ * Event — any scheduled gathering (meeting, call, workshop, review, etc.).
+ * `type` discriminates the kind of gathering for grouping/filtering. The
+ * default `meeting` preserves semantics for legacy meeting captures.
+ *
+ * Note: `deadline` is intentionally NOT a `type` value — deadlines are
+ * `task` entries with a `date` (the due date). Events are things you attend.
  */
-export const MeetingSchema = EntityBaseSchema.extend({
-    entity_type: z.literal('meeting'),
-    name: z.string().min(1, 'Meeting name/subject is required'),
-    category: z.string().optional().describe('Meeting category (e.g., internal, client, workshop, conference, industry-event)'),
+export const EVENT_TYPES = [
+    'meeting', 'call', 'review', 'workshop', 'presentation', 'conference', 'other',
+];
+export const EventSchema = EntityBaseSchema.extend({
+    entity_type: z.literal('event'),
+    name: z.string().min(1, 'Event name/subject is required'),
+    type: z.enum(EVENT_TYPES).default('meeting').describe('Kind of event'),
     attendees: z.array(z.string()).optional().describe('Attendee wikilinks'),
-    related_projects: z.array(z.string()).optional().describe('Related project wikilinks'),
-    related_organizations: z.array(z.string()).optional().describe('Related organization wikilinks'),
     location: z.string().optional().describe('Location or meeting link'),
-    duration: z.string().optional().describe('Duration (e.g., 30m, 1h)'),
+    start_date: dateField('start', 'Start date', 'When a multi-day event begins (omit for single-day events)'),
+    date: dateField('primary', 'Date', 'When the event takes place'),
 });
 /**
- * Decision — structured decision records (ADR-style)
- */
-export const DecisionSchema = EntityBaseSchema.extend({
-    entity_type: z.literal('decision'),
-    name: z.string().min(1, 'Decision name is required'),
-    status: z.enum(['proposed', 'accepted', 'rejected', 'deprecated', 'superseded'])
-        .default('proposed')
-        .describe('Current status'),
-    decision_makers: z.array(z.string()).optional().describe('People who made the decision'),
-    stakeholders: z.array(z.string()).optional().describe('People affected'),
-    context: z.string().optional().describe('Background and why this decision was needed'),
-    alternatives: z.string().optional().describe('Alternatives considered (markdown)'),
-    decision: z.string().optional().describe('The actual decision made'),
-    rationale: z.string().optional().describe('Why this decision was chosen'),
-    consequences: z.string().optional().describe('Outcomes and risks'),
-    supersedes: z.string().optional().describe('Decision this one replaces (wikilink)'),
-    superseded_by: z.string().optional().describe('Decision that replaces this one (wikilink)'),
-});
-/**
- * Task — lightweight action items and to-dos
+ * Task — lightweight action items and to-dos.
+ *
+ * `phase` is intentionally free-text (not a separate entity type or workspace
+ * config list). Phases vary widely across project types; the Timeline view
+ * auto-discovers distinct values per-project for grouping.
  */
 export const TaskSchema = EntityBaseSchema.extend({
     entity_type: z.literal('task'),
     name: z.string().min(1, 'Task name is required'),
-    status: z.enum(['open', 'in-progress', 'done', 'cancelled'])
-        .default('open')
+    status: z.enum(['backlog', 'todo', 'in-progress', 'in-review', 'done', 'cancelled'])
+        .default('backlog')
         .describe('Task status'),
     priority: z.enum(['low', 'medium', 'high', 'urgent'])
         .optional()
         .describe('Priority level'),
     assignee: z.string().optional().describe('Person assigned (wikilink)'),
-    due_date: z.string().optional().describe('Due date'),
-    description: z.string().optional().describe('Detailed description'),
+    phase: z.string().optional().describe('Project phase (free-text — Discover, Design, Prototype, Build, etc.)'),
+    start_date: dateField('start', 'Start date', 'Task start date (enables Timeline / Gantt rendering of duration)'),
+    date: dateField('primary', 'Due date', 'When the task is due'),
 });
 /**
- * Document — any authored document
- * Absorbs the former separate proposal, contract, brief, financial-plan, and template types.
+ * Deliverable — a scoped output promised to a client.
+ */
+export const DeliverableSchema = EntityBaseSchema.extend({
+    entity_type: z.literal('deliverable'),
+    name: z.string().min(1, 'Deliverable name is required'),
+    project: z.string().optional().describe('Parent project wikilink'),
+    status: z.enum(['planned', 'in-progress', 'delivered', 'accepted', 'rejected'])
+        .default('planned')
+        .describe('Delivery status'),
+    phase: z.string().optional().describe('Project phase (free-text — same semantics as task.phase)'),
+    start_date: dateField('start', 'Start date', 'Deliverable start date (enables Timeline rendering of duration)'),
+    date: dateField('primary', 'Due date', 'When the deliverable is due'),
+});
+// ══════════════════════════════════════════════════════════════════════════════
+// KM — authored (document, deck, publication, case-study, service, skill)
+// ══════════════════════════════════════════════════════════════════════════════
+/**
+ * Document — any authored document. The `guideline` category absorbs the
+ * former standalone `guideline` entity type.
  */
 export const DocumentSchema = EntityBaseSchema.extend({
     entity_type: z.literal('document'),
     name: z.string().min(1, 'Document name is required'),
-    category: z.string().optional().describe('Document category (e.g., proposal, contract, brief, memo, financial-plan, template, report)'),
-    client: z.string().optional().describe('Client organization wikilink'),
-    project: z.string().optional().describe('Related project wikilink'),
-    version: z.string().optional().describe('Version (e.g., v1, v2)'),
-    status: z.enum(['draft', 'sent', 'accepted', 'rejected', 'negotiating', 'signed', 'completed', 'terminated'])
+    category: z.enum(['proposal', 'contract', 'brief', 'memo', 'report', 'template', 'guideline', 'other'])
+        .optional()
+        .describe('Document category'),
+    status: z.enum(['draft', 'review', 'final', 'archived'])
         .default('draft')
         .describe('Document status'),
-    description: z.string().optional().describe('Description or summary'),
-});
-/**
- * Dataset — structured tabular data with typed columns and CSV body
- */
-export const ColumnDefinitionSchema = z.object({
-    name: z.string().min(1),
-    type: z.enum(['string', 'number', 'boolean', 'date']),
-    required: z.boolean().optional(),
-    description: z.string().optional(),
-});
-export const DatasetSchema = EntityBaseSchema.extend({
-    entity_type: z.literal('dataset'),
-    name: z.string().min(1, 'Dataset name is required'),
-    schema: z.array(ColumnDefinitionSchema).min(1, 'At least one column required'),
 });
 /**
- * Reference — external resources and inspiration
- * Absorbs the former separate technique type.
+ * Deck — a slide deck or presentation. Stays its own type alongside
+ * `document` because of the dedicated slides renderer + agent skills that
+ * pattern-match on `entity_type === 'deck'`.
  */
-export const ReferenceSchema = EntityBaseSchema.extend({
-    entity_type: z.literal('reference'),
-    name: z.string().min(1, 'Reference name is required'),
-    category: z.string().optional().describe('Reference category (e.g., article, video, tool, technique, framework, website)'),
-    source: z.string().optional().describe('Source/author'),
-    link: z.string().optional().describe('URL'),
-    related_projects: z.array(z.string()).optional().describe('Related project wikilinks'),
-    related_areas: z.array(z.string()).optional().describe('Related practice areas'),
-    description: z.string().optional().describe('Description'),
-});
-/**
- * Note — freeform thinking, research, scratch, daily notes
- * Lightweight entity with minimal schema. Participates in the graph like any other entity.
- */
-export const NoteSchema = EntityBaseSchema.extend({
-    entity_type: z.literal('note'),
-    name: z.string().min(1, 'Note name is required'),
-    category: z.string().optional().describe('Note category (e.g., research, scratch, daily, brainstorm, draft)'),
-});
-/**
- * Deliverable — a scoped contractual output promised to a client
- * Bridges the commercial side (proposal, contract) to execution (artifacts, tasks).
- */
-export const DeliverableSchema = EntityBaseSchema.extend({
-    entity_type: z.literal('deliverable'),
-    name: z.string().min(1, 'Deliverable name is required'),
-    project: z.string().optional().describe('Related project wikilink'),
-    status: z.enum(['planned', 'in-progress', 'delivered', 'accepted', 'rejected'])
-        .default('planned')
-        .describe('Delivery status'),
-    due_date: z.string().optional().describe('Due date'),
-    delivered_date: z.string().optional().describe('Actual delivery date'),
-    description: z.string().optional().describe('What this deliverable comprises'),
+export const DeckSchema = EntityBaseSchema.extend({
+    entity_type: z.literal('deck'),
+    name: z.string().min(1, 'Deck name is required'),
+    audience: z.enum(['client', 'team', 'board', 'external', 'other'])
+        .optional()
+        .describe('Intended audience'),
+    status: z.enum(['draft', 'review', 'final', 'archived'])
+        .default('draft')
+        .describe('Deck status'),
 });
 /**
- * Publication — authored content published externally
+ * Publication — authored content published externally.
  */
 export const PublicationSchema = EntityBaseSchema.extend({
     entity_type: z.literal('publication'),
     name: z.string().min(1, 'Publication name is required'),
-    category: z.string().optional().describe('Publication category (e.g., article, social-post, talk, podcast, award-submission)'),
-    platform: z.string().optional().describe('Platform (e.g., linkedin, medium, behance, conference)'),
+    platform: z.string().optional().describe('Where published (e.g., linkedin, medium, behance, conference)'),
     status: z.enum(['draft', 'review', 'scheduled', 'published'])
         .default('draft')
         .describe('Publication status'),
-    published_date: z.string().optional().describe('Date published'),
     url: z.string().optional().describe('URL of published content'),
-    related_projects: z.array(z.string()).optional().describe('Related project wikilinks'),
-    related_areas: z.array(z.string()).optional().describe('Related practice area wikilinks'),
 });
 /**
- * Deal — pre-project opportunity in the sales pipeline
+ * Case Study — portfolio narratives for completed projects.
  */
-export const DealSchema = EntityBaseSchema.extend({
-    entity_type: z.literal('deal'),
-    name: z.string().min(1, 'Deal name is required'),
+export const CaseStudySchema = EntityBaseSchema.extend({
+    entity_type: z.literal('case-study'),
+    name: z.string().min(1, 'Case study name is required'),
     client: z.string().optional().describe('Client organization wikilink'),
-    contacts: z.array(z.string()).optional().describe('Contact person wikilinks'),
-    stage: z.enum(['scoping', 'proposal', 'negotiating', 'won', 'lost'])
-        .default('scoping')
-        .describe('Pipeline stage'),
-    deal_value: z.number().optional().describe('Estimated deal value'),
-    probability: z.number().min(0).max(100).optional().describe('Win probability 0–100'),
-    expected_close: z.string().optional().describe('Expected close date'),
-    source: z.enum(['referral', 'inbound', 'outbound', 'repeat', 'partner', 'other'])
-        .optional()
-        .describe('How the opportunity originated'),
-    proposals: z.array(z.string()).optional().describe('Related proposal document wikilinks'),
-    project: z.string().optional().describe('Resulting project wikilink (once won)'),
-    lost_reason: z.string().optional().describe('Why the deal was lost'),
+    services: z.array(z.string()).optional()
+        .describe('Service entities this case study highlights (wikilinks)'),
+    date_range: z.string().optional().describe('Project timeframe (e.g., 2025-09 / 2026-01)'),
+    status: z.enum(['draft', 'review', 'final', 'published'])
+        .default('draft')
+        .describe('Case study status'),
+});
+/**
+ * Service — the firm's offerings + methodologies. Replaces the old
+ * `process` type and absorbs `practice-area` (top-level services replace
+ * what practice-area was trying to be).
+ *
+ * `sprint` links a granular service to its parent service (top-level
+ * services have none). `depends_on` / `enables` form a directed graph
+ * across the service set — the Graph view's most valuable use case.
+ */
+export const ServiceSchema = EntityBaseSchema.extend({
+    entity_type: z.literal('service'),
+    name: z.string().min(1, 'Service name is required'),
+    service_id: z.string().optional()
+        .describe('Optional human-readable id (e.g. "1.4") for studios that number their services'),
+    sprint: z.string().optional()
+        .describe('Parent service wikilink for hierarchy (top-level services / sprints have none)'),
+    depends_on: z.array(z.string()).optional()
+        .describe('Services that must precede this one (wikilinks)'),
+    enables: z.array(z.string()).optional()
+        .describe('Services that this one unlocks (wikilinks)'),
+    deliverables: z.array(z.string()).optional()
+        .describe('Named outputs this service produces'),
+    status: z.enum(['offered', 'in-development', 'retired'])
+        .default('offered')
+        .describe('Service lifecycle'),
+});
+/**
+ * Skill — prompt-level instructions the agent can load to teach it how to
+ * do a specific job. The entity id is the skill name used by `load_skill`.
+ * The body markdown is the instruction content.
+ *
+ * `applies_to` lets the agent load deck-skills when working on a deck,
+ * proposal-skills when on a `document.category=proposal`, etc. Empty /
+ * unset = generally applicable.
+ *
+ * The previous `loading: eager | on-demand` field is gone for graph-authored
+ * skills. Filesystem skills (shipped with the product in `src/agent/skills/`)
+ * keep their own loading mechanism via skill-loader.ts and orchestrator.ts.
+ *
+ * `name` and `description` are optional at creation so the sidebar new-entry
+ * flow works — the user fills them in afterward via the property panel.
+ */
+export const SkillSchema = EntityBaseSchema.extend({
+    entity_type: z.literal('skill'),
+    name: z.string().optional().describe('Human-readable title (falls back to entity id)'),
+    description: z.string().optional().describe('Shown in the skill index so the agent knows when to load it'),
+    applies_to: z.array(z.string()).optional()
+        .describe('Entity types this skill applies to (e.g. ["deck"]). Empty = generally applicable.'),
 });
 // ══════════════════════════════════════════════════════════════════════════════
-// KNOWLEDGE ENTITIES — typically in resource repos
+// CAPTURE — note, reference
 // ══════════════════════════════════════════════════════════════════════════════
 /**
- * Process — workflows, SOPs, and methodologies
+ * Note — freeform thinking, research, daily notes.
+ *
+ * Decisions migrated from the cut `decision` type land here as plain
+ * notes; operators may manually convert specific entries to `task` if they
+ * read better as work items.
  */
-export const ProcessSchema = EntityBaseSchema.extend({
-    entity_type: z.literal('process'),
-    name: z.string().min(1, 'Process name is required'),
-    description: z.string().optional().describe('Process description'),
-    steps: z.string().optional().describe('Process steps (markdown)'),
-    related_areas: z.array(z.string()).optional().describe('Related practice areas'),
-    owner: z.string().optional().describe('Person or team responsible (wikilink)'),
-    review_cycle: z.enum(['monthly', 'quarterly', 'annual', 'as-needed']).optional().describe('Review frequency'),
+export const NoteSchema = EntityBaseSchema.extend({
+    entity_type: z.literal('note'),
+    name: z.string().min(1, 'Note name is required'),
 });
 /**
- * Standard — guidelines and best practices
+ * Reference — external resources and inspiration.
  */
-export const StandardSchema = EntityBaseSchema.extend({
-    entity_type: z.literal('standard'),
-    name: z.string().min(1, 'Standard name is required'),
-    category: z.string().optional().describe('Category (e.g., accessibility, design-principles, code-standards)'),
-    description: z.string().optional().describe('Standard description'),
-    guidelines: z.string().optional().describe('Guidelines (markdown)'),
-    examples: z.array(z.string()).optional().describe('Example wikilinks'),
+export const ReferenceSchema = EntityBaseSchema.extend({
+    entity_type: z.literal('reference'),
+    name: z.string().min(1, 'Reference name is required'),
+    source: z.string().optional().describe('Source or author'),
+    link: z.string().optional().describe('URL'),
 });
 /**
- * Case Study — portfolio narratives for completed projects
+ * Dataset — a CSV the workspace owns, edited in a grid.
+ *
+ * Conventional CSV: the markdown body IS the data, and the header row IS the
+ * column list — there's no separate typed column schema. The grid editor
+ * (web CsvEditor) and the agent's `query_dataset` / `append_rows` tools read
+ * the body through CSVService (src/services/csv-service.ts), deriving columns
+ * from the header. Distinct from an uploaded `asset` with
+ * `asset_kind: 'spreadsheet'`, which is an opaque binary — a dataset is
+ * in-graph, queryable, and row-appendable.
  */
-export const CaseStudySchema = EntityBaseSchema.extend({
-    entity_type: z.literal('case-study'),
-    name: z.string().min(1, 'Case study name is required'),
-    client: z.string().optional().describe('Client organization wikilink'),
-    year: z.number().optional().describe('Year of the project'),
-    practice_areas: z.array(z.string()).optional().describe('Practice area wikilinks'),
-    sectors: z.array(z.string()).optional().describe('Industry tags'),
-    website_url: z.string().url().optional().describe('Project website URL'),
-    description: z.string().optional().describe('Short description'),
+export const DatasetSchema = EntityBaseSchema.extend({
+    entity_type: z.literal('dataset'),
+    name: z.string().min(1, 'Dataset name is required'),
+});
+// ══════════════════════════════════════════════════════════════════════════════
+// SYSTEM — asset
+// ══════════════════════════════════════════════════════════════════════════════
+/**
+ * Asset — a hosted binary the workspace owns. The frontmatter is the
+ * entity; the body is optional user notes. The binary itself lives in
+ * the asset backend (R2 or local volume) at `asset/{entity_id}/{file}`.
+ *
+ * Distinct from `reference`, which points at an external URL the
+ * workspace doesn't own. Per-kind UI (icon, viewer, thumbnail) is
+ * driven by `asset_kind`; see `detectAssetKind` in
+ * src/services/assets/base.ts.
+ *
+ * Asset is graph-visible (search, history, wikilinks) but hidden from the
+ * New Entry picker — it's created via the upload/drag-drop flow.
+ */
+export const ASSET_KINDS = [
+    'image', 'video', 'audio', 'pdf', 'spreadsheet', 'other',
+];
+export const AssetSchema = EntityBaseSchema.extend({
+    entity_type: z.literal('asset'),
+    name: z.string().min(1, 'Asset name is required'),
+    asset_url: z.string().min(1, 'asset_url is required').describe('Public URL or /api/assets/... path'),
+    asset_kind: z.enum(ASSET_KINDS).describe('High-level kind that drives icon and viewer'),
+    asset_extension: z.string().min(1).describe('Original file extension including the dot, e.g. ".csv"'),
+    asset_size: z.number().int().nonnegative().describe('Size in bytes'),
+    asset_mime: z.string().optional().describe('Detected MIME type'),
+    pages: z.number().int().positive().optional().describe('Page count (PDF only)'),
+    width: z.number().int().positive().optional().describe('Pixel width (image/video)'),
+    height: z.number().int().positive().optional().describe('Pixel height (image/video)'),
+    duration: z.number().nonnegative().optional().describe('Length in seconds (audio/video)'),
+    checksum: z.string().optional().describe('Content hash, e.g. sha256:...'),
 });
 // ══════════════════════════════════════════════════════════════════════════════
+// SYSTEM — comment (virtual entity, SQLite-backed)
+// ══════════════════════════════════════════════════════════════════════════════
+/**
+ * Comment — a threaded comment anchored to another entry. Unlike every other
+ * entity type, comments are NOT stored as markdown files; they live in
+ * `comments.db` (see `src/services/comment-service.ts`) for throughput.
+ * Agents see them as first-class typed entities through the virtual-entity
+ * adapter (`src/mcp/comment-virtual-entity.ts`), which is why the schema
+ * lives here alongside the file-backed types.
+ *
+ * The shape documents what fields the MCP envelope exposes; runtime
+ * validation happens inside CommentService itself.
+ */
+export const CommentSchema = EntityBaseSchema.extend({
+    entity_type: z.literal('comment'),
+    repo: z.string().describe('Folder the anchored entry lives in'),
+    entry_type: z.string().describe('Entity type of the anchored entry'),
+    entry_id: z.string().describe('Entity id of the anchored entry'),
+    thread_id: z.string().describe('Head comment id; replies share the same thread_id'),
+    parent_id: z.string().nullable().optional().describe('Parent comment id for replies, null on the head'),
+    author_user_id: z.number().int().describe('users.id of the author'),
+    author_role: z.enum(['user', 'agent']).describe('Whether the author was a human or the agent'),
+    anchor_quote: z.string().nullable().optional()
+        .describe('Original highlighted text at creation time, ≤256 chars (used for orphan rendering)'),
+    resolved_at: z.string().nullable().optional(),
+    resolved_by_user_id: z.number().int().nullable().optional(),
+    edited: z.boolean().optional(),
+    mentions: z.array(z.string()).optional().describe('Handles of mentioned users'),
+});
 // ══════════════════════════════════════════════════════════════════════════════
 // SCHEMA REGISTRY
 // ══════════════════════════════════════════════════════════════════════════════
 /**
- * Maps entity types to their Zod schemas.
- * 17 built-in types. App plugins register additional types at runtime via SchemaRegistry.
+ * Maps entity types to their Zod schemas. 17 canonical built-in types
+ * (16 user-facing + 1 system). Workspaces can register additional custom
+ * types via SchemaRegistry (schema_extensions).
  */
 export const ENTITY_SCHEMAS = {
-    // Identity (4)
+    // CRM (4)
     person: PersonSchema,
     organization: OrganizationSchema,
-    role: RoleSchema,
-    'practice-area': PracticeAreaSchema,
-    // Universal (10)
+    position: PositionSchema,
+    deal: DealSchema,
+    // PM (4)
     project: ProjectSchema,
-    meeting: MeetingSchema,
-    decision: DecisionSchema,
+    event: EventSchema,
     task: TaskSchema,
-    document: DocumentSchema,
-    dataset: DatasetSchema,
-    reference: ReferenceSchema,
-    note: NoteSchema,
     deliverable: DeliverableSchema,
+    // KM — authored (6)
+    document: DocumentSchema,
+    deck: DeckSchema,
     publication: PublicationSchema,
-    deal: DealSchema,
-    // Knowledge (3)
-    process: ProcessSchema,
-    standard: StandardSchema,
     'case-study': CaseStudySchema,
+    service: ServiceSchema,
+    skill: SkillSchema,
+    // Capture (3)
+    note: NoteSchema,
+    reference: ReferenceSchema,
+    dataset: DatasetSchema,
+    // System (2)
+    asset: AssetSchema,
+    comment: CommentSchema,
 };
 /**
  * Plural subfolder name → singular entity_type mapping
@@ -351,27 +457,47 @@ export const ENTITY_SCHEMAS = {
 export const PLURAL_TO_SINGULAR = {
     'people': 'person',
     'organizations': 'organization',
-    'roles': 'role',
-    'practice-areas': 'practice-area',
+    'positions': 'position',
+    'deals': 'deal',
     'projects': 'project',
-    'meetings': 'meeting',
-    'decisions': 'decision',
+    'events': 'event',
     'tasks': 'task',
-    'documents': 'document',
-    'datasets': 'dataset',
-    'references': 'reference',
-    'notes': 'note',
     'deliverables': 'deliverable',
+    'documents': 'document',
+    'decks': 'deck',
     'publications': 'publication',
-    'deals': 'deal',
-    'processes': 'process',
-    'standards': 'standard',
     'case-studies': 'case-study',
+    'services': 'service',
+    'skills': 'skill',
+    'notes': 'note',
+    'references': 'reference',
+    'datasets': 'dataset',
+    'assets': 'asset',
+    'comments': 'comment',
 };
 /**
  * Singular entity_type → plural subfolder name mapping
  */
 export const SINGULAR_TO_PLURAL = Object.fromEntries(Object.entries(PLURAL_TO_SINGULAR).map(([plural, singular]) => [singular, plural]));
+/**
+ * Cross-field task rule: a task's start date must not fall after its due date.
+ *
+ * This lives OUTSIDE the Zod schema on purpose. Expressing it as a
+ * `TaskSchema.refine(...)` would turn the ZodObject into a ZodEffects, which
+ * breaks shape introspection in schema-registry (`describeZodObject` and the
+ * schema_extensions `.extend()` path both rely on `instanceof z.ZodObject`) —
+ * and that powers the metadata field panel. So both validation entry points
+ * (this module's `validateEntity` and `graph.ts`'s private one) call this
+ * helper after a successful parse instead.
+ *
+ * `dateField` stores ISO 'YYYY-MM-DD' strings, so a lexicographic comparison
+ * is a correct date comparison.
+ */
+export function assertValidTaskDates(data) {
+    if (data.start_date && data.date && data.start_date > data.date) {
+        throw new Error(`Validation failed for task:\n  - start_date: Start date (${data.start_date}) must be on or before the due date (${data.date})`);
+    }
+}
 /**
  * Validation helper with helpful error messages
  */
@@ -381,11 +507,14 @@ export function validateEntity(entityType, data) {
         throw new Error(`Unknown entity type: ${entityType}`);
     }
     try {
-        return schema.parse(data);
+        const parsed = schema.parse(data);
+        if (entityType === 'task')
+            assertValidTaskDates(parsed);
+        return parsed;
     }
     catch (error) {
         if (error instanceof z.ZodError) {
-            const messages = error.errors.map(e => {
+            const messages = error.issues.map(e => {
                 const path = e.path.join('.');
                 return `  - ${path}: ${e.message}`;
             });
@@ -403,7 +532,7 @@ export function validateCustomEntity(data) {
     }
     catch (error) {
         if (error instanceof z.ZodError) {
-            const messages = error.errors.map(e => {
+            const messages = error.issues.map(e => {
                 const path = e.path.join('.');
                 return `  - ${path}: ${e.message}`;
             });