# your-domain-name

Adopt this skill: https://proskills.md/skills/other/sciknow-io-skillful-alhazen-skills-template

Page: https://proskills.md/skills/other/sciknow-io-skillful-alhazen-skills-template
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/_template/SKILL.md
size: 2201
sha: bdfcab23b8fe97ca7d8de896831b4cf50504561b
upstream: https://github.com/sciknow-io/skillful-alhazen/blob/main/skills/_template/SKILL.md

````text
---
name: your-domain-name
description: Brief description of what this skill does
---

# Your Domain Name Skill

Use this skill to [describe primary use case]. Claude acts as [describe Claude's role in this domain].

**When to use:** [Triggers: "ingest [item]", "analyze [item]", "show [entity]", ...]

## Prerequisites

- TypeDB must be running: `make db-start`
- Dependencies installed: `uv sync --all-extras` (from project root)
- Schema loaded: run `make build-db` after adding your `schema.tql`

## Environment Variables

- `TYPEDB_HOST`: TypeDB server (default: localhost)
- `TYPEDB_PORT`: TypeDB port (default: 1729)
- `TYPEDB_DATABASE`: Database name (default: alhazen_notebook)

## Quick Start

```bash
uv run python .claude/skills/<your-domain>/<your-domain>.py list-entities
```

## Schema Gap Recognition

During sensemaking, if you encounter a concept, relationship, or entity type that has no place in the current TypeDB schema, that is a **schema gap** — a signal for schema evolution, not a failure.

When you notice a schema gap:
1. Complete as much as possible with the current schema (partial knowledge > none)
2. Immediately file a gap issue:

```bash
gh issue create --repo <owner/name> \
  --title "Gap [moderate][entity-schema]: <one-sentence summary>" \
  --body $'## What was missing\n<the concept you tried to represent>\n\n## What broke\n<which TypeDB entity/relation/attribute is absent>\n\n## Suggested fix\n<proposed TypeQL addition, or unknown>' \
  --label "gap:open"
```

**Examples of schema gaps:**
- A paper has a methodology section but there's no `methodology` attribute on `scilit-paper`
- A job posting mentions a work arrangement type that isn't in the schema
- A disease has a phenotype frequency that can't be attached to the current relation

Use `--dry-run` first to review the issue before filing it.

## Command Output Pattern

`uv run` emits a `VIRTUAL_ENV` warning to stderr. Always use `2>/dev/null` when piping output to a JSON parser — never `2>&1`, which merges the warning into stdout and breaks JSON parsing.

**Before executing any commands, read `USAGE.md` in this directory for the complete command reference, workflows, and data model.**
````

## File: skills/_template/README.md
size: 1973
sha: 4e3690163962ccbf9239b4624b3f8dcd6e6683a7
upstream: https://github.com/sciknow-io/skillful-alhazen/blob/main/skills/_template/README.md

````text
# Skill Template

This directory contains template files for creating new skills. Use these as a starting point when building a new domain skill.

## Files

| File | Purpose |
|------|---------|
| `SKILL.md` | Template for skill documentation (what Claude reads) |
| `template.py` | Template for CLI script (TypeDB operations) |
| `schema.tql` | Template for TypeDB schema (data model) |

## Quick Start

1. **Copy this directory:**
   ```bash
   cp -r .claude/skills/_template .claude/skills/<your-domain>
   ```

2. **Rename the script:**
   ```bash
   mv .claude/skills/<your-domain>/template.py .claude/skills/<your-domain>/<your-domain>.py
   ```

3. **Edit the schema (`schema.tql`):**
   - Replace `DOMAIN` with your domain name
   - Define your attributes, entities, and relations
   - Copy to `local_resources/typedb/namespaces/<your-domain>.tql`

4. **Edit the script (`<your-domain>.py`):**
   - Replace `DOMAIN` with your domain name
   - Implement your commands
   - Add argparse subcommands

5. **Edit `SKILL.md`:**
   - Fill in the frontmatter
   - Document your commands
   - Describe the sensemaking workflow

6. **Load the schema:**
   ```bash
   docker exec -i alhazen-typedb /opt/typedb-all-linux-x86_64/typedb console --server=localhost:1729 << 'EOF'
   transaction alhazen_notebook schema write
   source /schema/namespaces/<your-domain>.tql
   commit
   EOF
   ```

7. **Test:**
   ```bash
   uv run python .claude/skills/<your-domain>/<your-domain>.py --help
   ```

## Checklist

Before your skill is complete:

- [ ] Schema loaded into TypeDB
- [ ] Script has `--help` for all commands
- [ ] Script outputs JSON to stdout
- [ ] SKILL.md has complete command reference
- [ ] SKILL.md documents sensemaking workflow
- [ ] Tested with Claude Code

## Architecture Reference

See the wiki page [Skill-Architecture](https://github.com/GullyBurns/skillful-alhazen/wiki/Skill-Architecture) for detailed documentation on the three-component architecture.
````

## File: skills/_template/pipelines/pipeline_template.py
size: 8726
sha: ccf3c5d2d7d4e8f0301c068a5f8b6bf196252c1e
upstream: https://github.com/sciknow-io/skillful-alhazen/blob/main/skills/_template/pipelines/pipeline_template.py

```text
"""
<YourSkill> Assessment Pipeline -- Hamilton DAG

This is the canonical Analysis phase pipeline template for TypeDB-backed curation skills.
Copy and adapt for your skill's analysis challenge.

Nodes:
  fetch_records(investigation_id)  -> raw list of dicts from TypeDB
  parse_records(fetch_records)     -> List[EntityAssessment]  (Pydantic-validated)
  table_data(parse_records)        -> JSON string  (stored in TypeDB analysis.content)
  plot_code(parse_records)         -> Observable Plot JS expression  (stored in TypeDB analysis.plot-code)

Node graph:
  fetch_records(investigation_id)
          |
    parse_records()
        /         \\
  table_data()   plot_code()

Register via:
  <skill>.py add-pipeline \\
    --investigation <ID> \\
    --title "My Analysis" \\
    --analysis-type pipeline-plot \\
    --pipeline-script "@skills/<skill>/pipelines/pipeline_template.py" \\
    --pipeline-config '{"outputs":["plot_code","table_data"],"inputs":{"investigation_id":"<ID>"},"env_inputs":{}}'

Run via:
  <skill>.py run-pipeline --id <analysis-id>

Schema evolution: add Optional fields to Pydantic models and re-run -- no data migration needed.
"""
from __future__ import annotations

import json
import os
import re
import sys
from pathlib import Path
from typing import Optional

# Uncomment and update once you have defined your Pydantic models:
# sys.path.insert(0, str(Path(__file__).parent.parent))
# from eval_models import EntityAssessment, DimensionScores, EntityCategory

# ── CONFIGURATION ─────────────────────────────────────────────────
TYPEDB_HOST = os.environ.get("TYPEDB_HOST", "localhost")
TYPEDB_PORT = int(os.environ.get("TYPEDB_PORT", 1729))
TYPEDB_DATABASE = os.environ.get("TYPEDB_DATABASE", "alh_core")
TYPEDB_PASSWORD = os.environ.get("TYPEDB_PASSWORD", "password")

# Keyword -> dimension field mapping for score table parsing.
# The sensemaking agent writes criterion labels that may vary slightly across runs.
# List keywords that should map to each dimension field.
DIMENSION_KEYWORDS: list[tuple[list[str], str]] = [
    (["dimension_a", "alias_a"], "dimension_a"),
    (["dimension_b", "alias_b"], "dimension_b"),
]

# Regex: matches a markdown table row like "| criterion | 2 | explanation |"
_SCORE_ROW_RE = re.compile(
    r"^\s*\|\s*([^|]+?)\s*\|\s*(\d)\s*[/|]",
    re.MULTILINE,
)

# ── HAMILTON NODES ─────────────────────────────────────────────────

def fetch_records(investigation_id: str) -> list[dict]:
    """
    Fetch all entities + their assessment notes from TypeDB.

    Returns a list of dicts with keys: entity_id, entity_name, note_content (str or None).
    Adapt the TypeQL query to match your skill's schema.
    """
    from typedb.driver import Credentials, DriverOptions, TransactionType, TypeDB

    driver = TypeDB.driver(
        f"{TYPEDB_HOST}:{TYPEDB_PORT}",
        Credentials("admin", TYPEDB_PASSWORD),
        DriverOptions(is_tls_enabled=False),
    )

    records = []
    try:
        # Step 1: get all entities in scope
        with driver.transaction(TYPEDB_DATABASE, TransactionType.READ) as tx:
            entities = list(tx.query(f'''
                match
                  $ctx isa <your-collection-type>, has id "{investigation_id}";
                  $ent isa <your-entity-type>, has id $ent_id, has name $ent_name;
                  (investigation: $ctx, system: $ent) isa investigated-in;
                fetch {{
                  "entity_id": $ent_id,
                  "entity_name": $ent_name
                }};
            ''').resolve())

        for ent in entities:
            eid = ent["entity_id"]
            content = None
            # Step 2: fetch the assessment note for each entity
            with driver.transaction(TYPEDB_DATABASE, TransactionType.READ) as tx:
                notes = list(tx.query(f'''
                    match
                      $ent isa <your-entity-type>, has id "{eid}";
                      $note isa note, has topic "assessment", has content $content;
                      (subject: $ent, note: $note) isa aboutness;
                    fetch {{ "content": $content }};
                ''').resolve())
                if notes:
                    content = notes[0].get("content")

            records.append({
                "entity_id": eid,
                "entity_name": ent["entity_name"],
                "note_content": content,
            })

    finally:
        driver.close()

    return records

def parse_records(fetch_records: list[dict]) -> list[dict]:
    """
    Parse raw records into validated assessment dicts.

    Once you define your Pydantic models, replace `list[dict]` with
    `list[EntityAssessment]` and uncomment the Pydantic validation block.
    """
    results = []

    for record in fetch_records:
        eid = record["entity_id"]
        ename = record["entity_name"]
        content: Optional[str] = record.get("note_content")
        warnings: list[str] = []

        # Initialise dimension scores to 0
        dim_scores: dict[str, int] = {field: 0 for _, field in DIMENSION_KEYWORDS}

        if content is None:
            warnings.append("no assessment note found; all scores default to 0")
        else:
            rows = _SCORE_ROW_RE.findall(content)
            if not rows:
                warnings.append(
                    "assessment note has no parseable score table; all scores default to 0"
                )
            else:
                found_dims: set[str] = set()
                for criterion_text, score_str in rows:
                    criterion_lower = criterion_text.lower()
                    for keywords, field in DIMENSION_KEYWORDS:
                        if any(kw in criterion_lower for kw in keywords):
                            dim_scores[field] = int(score_str)
                            found_dims.add(field)
                            break

                missing = set(dim_scores.keys()) - found_dims
                if missing:
                    warnings.append(
                        f"dimensions not found in table (defaulted to 0): {sorted(missing)}"
                    )

        total = sum(dim_scores.values())

        # Replace with Pydantic validation once models are defined:
        # assessment = EntityAssessment(
        #     id=eid, name=ename,
        #     scores=DimensionScores(**dim_scores),
        #     parse_warnings=warnings,
        # )
        # results.append(assessment.model_dump(mode="json"))

        results.append({
            "id": eid,
            "name": ename,
            "scores": {**dim_scores, "total": total},
            "parse_warnings": warnings,
        })

    # Sort by total score descending
    results.sort(key=lambda r: -r["scores"]["total"])
    return results

def table_data(parse_records: list[dict]) -> list[dict]:
    """
    Return validated assessments as a list of dicts.
    run-pipeline serialises this via json.dumps() into TypeDB analysis.content.
    The dashboard then JSON.parse()s it back into the `data` variable for the plot.
    """
    return parse_records

def plot_code(parse_records: list[dict]) -> str:
    """
    Return an Observable Plot JS expression.
    Stored in TypeDB analysis.plot-code.

    The dashboard evaluates this with `data` bound to the parsed table_data JSON array
    and `Plot` bound to the Observable Plot library.

    Replace this placeholder with your actual visualization.
    """
    return r"""
Plot.plot({
  width: 700, height: 400,
  marks: [
    Plot.barY(data, {
      x: "name",
      y: d => d.scores?.total ?? 0,
      fill: "steelblue",
      tip: true
    }),
    Plot.ruleY([0])
  ],
  x: {tickRotate: -45, label: null},
  y: {label: "Total score"}
})
""".strip()

# ── RUNNER (called by run-pipeline) ───────────────────────────────

if __name__ == "__main__":
    import hamilton.driver as hd

    investigation_id = os.environ.get("INVESTIGATION_ID", "")
    if not investigation_id:
        print(json.dumps({"success": False, "error": "INVESTIGATION_ID env var not set"}))
        sys.exit(1)

    dr = hd.Builder().with_modules(sys.modules[__name__]).build()
    outputs = dr.execute(
        ["table_data", "plot_code"],
        inputs={"investigation_id": investigation_id},
    )
    preview = {
        k: (v[:200] + "...") if isinstance(v, str) and len(v) > 200 else v
        for k, v in outputs.items()
    }
    print(json.dumps({"success": True, "outputs": preview}))
```

## File: skills/_template/schema.tql
size: 3677
sha: 4a69dc8da983c6a0b318249b03b17ee34765dd52
upstream: https://github.com/sciknow-io/skillful-alhazen/blob/main/skills/_template/schema.tql

```text
# =============================================================================
# [DOMAIN NAME] NAMESPACE - TypeDB 3.x Schema Extension
# =============================================================================
# Domain-specific subtypes for [description].
# Namespace prefix: DOMAIN-*
# ALL entity, relation, and attribute types below MUST start with "DOMAIN-"
# This prefix is declared in skill.yaml -> schema.namespace
# =============================================================================

define

# -----------------------------------------------------------------------------
# ATTRIBUTE TYPES - Domain Specific
# -----------------------------------------------------------------------------

# TODO: Define your domain-specific attributes
# Pattern: attribute DOMAIN-attr-name, value [string|integer|double|boolean|datetime];

# URL attributes
# domain-url sub attribute, value string;

# Status/state attributes
# domain-status sub attribute, value string;

# Measurement/score attributes
# domain-score sub attribute, value double;

# Date attributes
# domain-date sub attribute, value datetime;

# -----------------------------------------------------------------------------
# ENTITY TYPES - Things
# -----------------------------------------------------------------------------

# TODO: Define your primary entity types
# Pattern: domain-thing sub domain-thing,
#     owns domain-attribute,
#     plays domain-relation:role;

# DOMAIN-ENTITY - Primary thing you track
# domain-entity sub domain-thing,
#     owns domain-url,
#     owns domain-status,
#     plays domain-relation:role1;

# -----------------------------------------------------------------------------
# ENTITY TYPES - Artifacts (raw captured content)
# -----------------------------------------------------------------------------

# TODO: Define artifact types for raw content storage
# Pattern: domain-artifact-type sub artifact;

# DOMAIN-CONTENT - Raw content from source
# domain-content sub artifact;

# -----------------------------------------------------------------------------
# ENTITY TYPES - Fragments (extracted pieces)
# -----------------------------------------------------------------------------

# TODO: Define fragment types for extracted pieces
# Pattern: domain-fragment sub fragment,
#     owns fragment-specific-attribute,
#     plays domain-relation:role;

# DOMAIN-FRAGMENT - Extracted piece of content
# domain-fragment sub fragment,
#     owns domain-attribute,
#     plays domain-relation:role2;

# -----------------------------------------------------------------------------
# ENTITY TYPES - Notes (Claude's analysis)
# -----------------------------------------------------------------------------

# TODO: Define note types for different kinds of analysis
# Pattern: domain-note-type sub note,
#     owns note-specific-attribute;

# DOMAIN-ANALYSIS-NOTE - Claude's analysis
# domain-analysis-note sub note,
#     owns domain-score;

# DOMAIN-RESEARCH-NOTE - Research findings
# domain-research-note sub note;

# -----------------------------------------------------------------------------
# RELATION TYPES - Domain Specific
# -----------------------------------------------------------------------------

# TODO: Define relations between your entities
# Pattern: domain-relation sub relation,
#     relates role1,
#     relates role2;

# DOMAIN-RELATION - Links entity1 to entity2
# domain-relation sub relation,
#     relates role1,
#     relates role2;

# =============================================================================
# END [DOMAIN NAME] NAMESPACE
# =============================================================================
```

## File: skills/_template/schema/eval_schema_template.yaml
size: 3695
sha: 805ca36578fe4ff7b803a7eff26bbe2f98df6e18
upstream: https://github.com/sciknow-io/skillful-alhazen/blob/main/skills/_template/schema/eval_schema_template.yaml

```text
id: https://sciknow.io/<your-skill>-eval-schema
name: <your-skill>-eval-schema
description: >
  Schema for evaluating <domain entities> on curation dimensions.
  Extend by adding optional fields -- existing records stay valid (additive evolution).
  Rename this file and update the id/name prefixes for your skill.

prefixes:
  linkml: https://w3id.org/linkml/
  meval: https://sciknow.io/<your-skill>-eval/

default_prefix: meval
default_range: string
imports:
  - linkml:types

# ── TYPES ─────────────────────────────────────────────────────────
# Score is the canonical dimension score type used across curation skills.
# All six standard dimensions use 0-3 integer scores.
types:
  Score:
    uri: xsd:integer
    base: int
    description: Integer 0-3 (0=none, 1=partial, 2=substantial, 3=full)
    minimum_value: 0
    maximum_value: 3

# ── ENUMERATIONS ──────────────────────────────────────────────────
# Add domain-specific enumerations here. Example:
enums:
  EntityCategory:
    description: High-level category for the thing being assessed
    permissible_values:
      tool:
        description: A deployed software tool
      benchmark:
        description: An evaluation benchmark
      paper:
        description: A research paper without a deployed artifact

# ── CLASSES ───────────────────────────────────────────────────────
classes:

  DimensionScores:
    description: >
      Scores on the curation assessment dimensions.
      Replace dimension_a / dimension_b with your actual dimensions.
      Add a model_validator in the Pydantic implementation to compute `total`.
    attributes:
      dimension_a:
        range: Score
        required: true
        description: First dimension -- replace with your dimension name and description
      dimension_b:
        range: Score
        required: true
        description: Second dimension -- replace with your dimension name and description
      total:
        range: integer
        description: Sum of all dimension scores (derived -- computed in Pydantic model_validator)
        ifabsent: int(0)

  EntityAssessment:
    description: >
      Complete assessment record for one entity.
      One record per entity in the skill's knowledge base.
      This is the top-level unit of analysis -- a row in the visualization.
    tree_root: true
    attributes:
      id:
        identifier: true
        range: string
        description: Stable TypeDB entity id (e.g. trs-xxxxx or your-entity-xxxxx)
      name:
        required: true
        range: string
        description: Display name
      category:
        required: true
        range: EntityCategory
        description: High-level category (replace EntityCategory with your enum)
      scores:
        required: true
        range: DimensionScores
        inlined: true
        description: Scores on the curation assessment dimensions
      tags:
        multivalued: true
        range: string
        description: Free-form classification tags
      assessment_summary:
        range: string
        description: Free-text synthesis drawn from sensemaking notes
      parse_warnings:
        multivalued: true
        range: string
        description: >
          Warnings emitted during score parsing.
          Populated when notes are missing or score tables are not found.
          Use for data quality tracking.
```

## File: skills/_template/skill.yaml
size: 1064
sha: 1cf7557505053425d7846436c0721115b6a78ead
upstream: https://github.com/sciknow-io/skillful-alhazen/blob/main/skills/_template/skill.yaml

```text
name: DOMAIN
description: "Brief description of what this skill does"
license: Apache-2.0
compatibility: "TypeDB 3.x"

# Core files
script: template.py
schema: schema.tql

# Schema namespace — all types in schema.tql must start with this prefix
schema:
  namespace: DOMAIN              # e.g., jobhunt, tech-recon, scilit
  depends_on: []                 # skill names whose schemas must load first

# Dependencies
requires:
  bins: [uv, docker]
  env: [TYPEDB_HOST, TYPEDB_PORT, TYPEDB_DATABASE]
  optional_env: []

# CLI operations
operations:
  ingestion:
    - ingest
    - add-entity
  artifacts:
    - list-artifacts
    - show-artifact
  queries:
    - list-entities
    - show-entity
  updates:
    - add-note
    - tag
    - search-tag

# TypeDB entity types defined in schema.tql
entity_types:
  - DOMAIN-entity     # replace with actual entity type name

# Bundle metadata — used by make package-skill and make install-skill
bundle:
  schema_check_type: DOMAIN-entity   # first entity type in schema.tql
  zip_name: DOMAIN-v1.0.zip
  version: "1.0"
```

## File: skills/_template/template.py
size: 25318
sha: 12794168f73485041d378626a5e0a4b92121d8ea
upstream: https://github.com/sciknow-io/skillful-alhazen/blob/main/skills/_template/template.py

```text
#!/usr/bin/env python3
"""
[DOMAIN NAME] CLI - [Brief description].

This script handles INGESTION and QUERIES. Claude handles SENSEMAKING via the SKILL.md.

Usage:
    python .claude/skills/DOMAIN/DOMAIN.py <command> [options]

Commands:
    # Ingestion
    ingest              Fetch content from URL and store as artifact
    add-entity          Add an entity manually

    # Artifacts (for Claude's sensemaking)
    list-artifacts      List artifacts by analysis status
    show-artifact       Get artifact content for Claude to read

    # Queries
    list-entities       List all entities
    show-entity         Get entity details

    # Updates
    update-status       Update entity status
    add-note            Create a note about any entity
    tag                 Tag an entity
    search-tag          Search by tag

Environment:
    TYPEDB_HOST       TypeDB server host (default: localhost)
    TYPEDB_PORT       TypeDB server port (default: 1729)
    TYPEDB_DATABASE   Database name (default: alhazen_notebook)
    ALHAZEN_CACHE_DIR File cache directory (default: ~/.alhazen/cache)
"""

import argparse
import json
import os
import sys
from pathlib import Path

# Add src to path for imports
sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "src"))

# Optional: for URL fetching
try:
    import requests
    from bs4 import BeautifulSoup

    REQUESTS_AVAILABLE = True
except ImportError:
    REQUESTS_AVAILABLE = False

# TypeDB driver
try:
    from typedb.driver import Credentials, DriverOptions, TransactionType, TypeDB

    TYPEDB_AVAILABLE = True
except ImportError:
    TYPEDB_AVAILABLE = False
    print(
        "Warning: typedb-driver not installed. Install with: pip install 'typedb-driver>=3.0.0'",
        file=sys.stderr,
    )

try:
    from skillful_alhazen.utils.skill_helpers import (
        escape_string, generate_id, get_timestamp, check_infrastructure,
    )
except ImportError:
    import uuid
    from datetime import datetime, timezone

    def escape_string(s: str) -> str:
        if s is None:
            return ""
        return s.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n").replace("\r", "")

    def generate_id(prefix: str) -> str:
        return f"{prefix}-{uuid.uuid4().hex[:12]}"

    def get_timestamp() -> str:
        return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S")

    def check_infrastructure(*args, **kwargs): pass  # no-op if pkg unavailable

# Cache utilities for large artifacts
try:
    from skillful_alhazen.utils.cache import (
        save_to_cache,
        load_from_cache_text,
        should_cache,
        get_cache_stats,
        format_size,
    )

    CACHE_AVAILABLE = True
except ImportError:
    CACHE_AVAILABLE = False
    # Fallback: define minimal versions if cache module not available
    def should_cache(content):
        return False

    def get_cache_stats():
        return {"error": "Cache module not available"}

    def format_size(size):
        return f"{size} bytes"

# =============================================================================
# CONFIGURATION
# =============================================================================

TYPEDB_HOST = os.getenv("TYPEDB_HOST", "localhost")
TYPEDB_PORT = int(os.getenv("TYPEDB_PORT", "1729"))
TYPEDB_DATABASE = os.getenv("TYPEDB_DATABASE", "alh_core")
TYPEDB_USERNAME = os.getenv("TYPEDB_USERNAME", "admin")
TYPEDB_PASSWORD = os.getenv("TYPEDB_PASSWORD", "password")

# TODO: Update these constants for your domain
DOMAIN_PREFIX = "domain"  # e.g., "jobhunt", "scilit"
ENTITY_TYPE = f"{DOMAIN_PREFIX}-entity"
ARTIFACT_TYPE = f"{DOMAIN_PREFIX}-artifact"

# =============================================================================
# UTILITIES
# =============================================================================

def get_driver():
    """Get TypeDB driver connection."""
    return TypeDB.driver(
        f"{TYPEDB_HOST}:{TYPEDB_PORT}",
        Credentials(TYPEDB_USERNAME, TYPEDB_PASSWORD),
        DriverOptions(is_tls_enabled=False),
    )

def get_attr(entity: dict, attr_name: str, default=None):
    """Safely extract attribute value from a TypeDB 3.x fetch result dict."""
    return entity.get(attr_name, default)

def fetch_url_content(url: str) -> tuple[str, str]:
    """
    Fetch URL and return (title, text_content).

    Returns basic parsed content - Claude will do the intelligent extraction.
    """
    if not REQUESTS_AVAILABLE:
        return "", ""

    headers = {"User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36"}

    try:
        response = requests.get(url, headers=headers, timeout=30)
        response.raise_for_status()

        soup = BeautifulSoup(response.text, "html.parser")

        # Remove script and style elements
        for element in soup(["script", "style", "nav", "footer", "header"]):
            element.decompose()

        title = soup.title.string if soup.title else ""

        # Get text content
        text = soup.get_text(separator="\n", strip=True)

        # Clean up whitespace
        lines = [line.strip() for line in text.splitlines() if line.strip()]
        text = "\n".join(lines)

        # Limit content size
        if len(text) > 50000:
            text = text[:50000] + "\n... [truncated]"

        return title, text

    except Exception as e:
        print(f"Error fetching URL: {e}", file=sys.stderr)
        return "", ""

# =============================================================================
# INGESTION COMMANDS
# =============================================================================

def cmd_ingest(args):
    """
    Fetch content from URL and store as artifact.

    This implements the INGESTION phase of the curation pattern:
    - Fetches URL content (raw, unedited)
    - Stores as artifact with provenance
    - Creates placeholder entity
    - Claude does the SENSEMAKING separately
    """
    if not REQUESTS_AVAILABLE:
        print(json.dumps({"success": False, "error": "requests/beautifulsoup4 not installed"}))
        return

    url = args.url
    title, content = fetch_url_content(url)

    if not content:
        print(json.dumps({"success": False, "error": "Could not fetch URL content"}))
        return

    # Generate IDs
    entity_id = generate_id("entity")
    artifact_id = generate_id("artifact")
    timestamp = get_timestamp()

    placeholder_name = title if title else f"Content from {url[:50]}"

    with get_driver() as driver:
        # Create entity placeholder
        with driver.transaction(TYPEDB_DATABASE, TransactionType.WRITE) as tx:
            entity_query = f'''insert $e isa {ENTITY_TYPE},
                has id "{entity_id}",
                has name "{escape_string(placeholder_name)}",
                has created-at {timestamp};'''
            tx.query(entity_query).resolve()
            tx.commit()

        # Create artifact with content (inline or cached)
        with driver.transaction(TYPEDB_DATABASE, TransactionType.WRITE) as tx:
            # Check if content should be cached externally (>50KB)
            if CACHE_AVAILABLE and should_cache(content):
                # Store in cache
                cache_result = save_to_cache(
                    artifact_id=artifact_id,
                    content=content,
                    mime_type="text/html",
                )
                artifact_query = f'''insert $a isa {ARTIFACT_TYPE},
                    has id "{artifact_id}",
                    has name "Content: {escape_string(placeholder_name)}",
                    has cache-path "{cache_result['cache_path']}",
                    has mime-type "text/html",
                    has file-size {cache_result['file_size']},
                    has content-hash "{cache_result['content_hash']}",
                    has source-uri "{escape_string(url)}",
                    has created-at {timestamp};'''
            else:
                # Store inline in TypeDB
                artifact_query = f'''insert $a isa {ARTIFACT_TYPE},
                    has id "{artifact_id}",
                    has name "Content: {escape_string(placeholder_name)}",
                    has content "{escape_string(content)}",
                    has source-uri "{escape_string(url)}",
                    has created-at {timestamp};'''
            tx.query(artifact_query).resolve()
            tx.commit()

        # Link artifact to entity
        with driver.transaction(TYPEDB_DATABASE, TransactionType.WRITE) as tx:
            rep_query = f'''match
                $a isa {ARTIFACT_TYPE}, has id "{artifact_id}";
                $e isa {ENTITY_TYPE}, has id "{entity_id}";
            insert (artifact: $a, referent: $e) isa representation;'''
            tx.query(rep_query).resolve()
            tx.commit()

        # Add tags if specified
        if args.tags:
            for tag_name in args.tags:
                tag_id = generate_id("tag")
                with driver.transaction(TYPEDB_DATABASE, TransactionType.READ) as tx:
                    tag_check = f'match $t isa tag, has name "{tag_name}"; fetch {{ "id": $t.id }};'
                    existing_tag = list(tx.query(tag_check).resolve())

                if not existing_tag:
                    with driver.transaction(TYPEDB_DATABASE, TransactionType.WRITE) as tx:
                        tx.query(
                            f'insert $t isa tag, has id "{tag_id}", has name "{tag_name}";'
                        ).resolve()
                        tx.commit()

                with driver.transaction(TYPEDB_DATABASE, TransactionType.WRITE) as tx:
                    tx.query(f'''match
                        $e isa {ENTITY_TYPE}, has id "{entity_id}";
                        $t isa tag, has name "{tag_name}";
                    insert (tagged-entity: $e, tag: $t) isa tagging;''').resolve()
                    tx.commit()

    print(
        json.dumps(
            {
                "success": True,
                "entity_id": entity_id,
                "artifact_id": artifact_id,
                "url": url,
                "content_length": len(content),
                "status": "raw",
                "message": "Content ingested. Artifact stored - ask Claude to 'analyze this' for sensemaking.",
            },
            indent=2,
        )
    )

def cmd_add_entity(args):
    """Add an entity manually."""
    entity_id = args.id or generate_id("entity")
    timestamp = get_timestamp()

    query = f'''insert $e isa {ENTITY_TYPE},
        has id "{entity_id}",
        has name "{escape_string(args.name)}",
        has created-at {timestamp}'''

    if args.description:
        query += f', has description "{escape_string(args.description)}"'

    query += ";"

    with get_driver() as driver:
        with driver.transaction(TYPEDB_DATABASE, TransactionType.WRITE) as tx:
            tx.query(query).resolve()
            tx.commit()

    print(json.dumps({"success": True, "entity_id": entity_id, "name": args.name}))

# =============================================================================
# ARTIFACT COMMANDS
# =============================================================================

def cmd_list_artifacts(args):
    """List artifacts, optionally filtered by analysis status."""
    with get_driver() as driver:
        with driver.transaction(TYPEDB_DATABASE, TransactionType.READ) as tx:
            query = f"""match
                $a isa {ARTIFACT_TYPE};
            fetch {{ "id": $a.id, "name": $a.name, "source-uri": $a.source-uri, "created-at": $a.created-at }};"""
            artifacts = list(tx.query(query).resolve())

            results = []
            for art in artifacts:
                artifact_id = art.get("id")

                # Check for notes (simple heuristic for "analyzed")
                notes_query = f'''match
                    $a isa {ARTIFACT_TYPE}, has id "{artifact_id}";
                    (artifact: $a, referent: $e) isa representation;
                    (note: $n, subject: $e) isa aboutness;
                fetch {{ "id": $n.id }};'''

                try:
                    notes = list(tx.query(notes_query).resolve())
                    has_notes = len(notes) > 0
                except Exception:
                    has_notes = False

                status = "analyzed" if has_notes else "raw"

                if args.status and args.status != "all":
                    if args.status != status:
                        continue

                results.append(
                    {
                        "id": artifact_id,
                        "name": art.get("name"),
                        "source_url": art.get("source-uri"),
                        "created_at": art.get("created-at"),
                        "status": status,
                    }
                )

    print(
        json.dumps(
            {
                "success": True,
                "artifacts": results,
                "count": len(results),
                "filter": args.status or "all",
            },
            indent=2,
        )
    )

def cmd_show_artifact(args):
    """Get artifact content for Claude to read during sensemaking."""
    with get_driver() as driver:
        with driver.transaction(TYPEDB_DATABASE, TransactionType.READ) as tx:
            # Include cache attributes in fetch
            query = f'''match
                $a isa {ARTIFACT_TYPE}, has id "{args.id}";
            fetch {{ "id": $a.id, "name": $a.name, "content": $a.content, "cache-path": $a.cache-path, "mime-type": $a.mime-type, "file-size": $a.file-size, "source-uri": $a.source-uri, "created-at": $a.created-at }};'''
            result = list(tx.query(query).resolve())

            if not result:
                print(json.dumps({"success": False, "error": "Artifact not found"}))
                return

            # Get linked entity
            entity_query = f'''match
                $a isa {ARTIFACT_TYPE}, has id "{args.id}";
                (artifact: $a, referent: $e) isa representation;
            fetch {{ "id": $e.id, "name": $e.name }};'''
            entity_result = list(tx.query(entity_query).resolve())

    art = result[0]

    # Get content - either from inline content or from cache
    cache_path = art.get("cache-path")
    if cache_path and CACHE_AVAILABLE:
        # Load from cache
        try:
            content = load_from_cache_text(cache_path)
            storage = "cache"
        except FileNotFoundError:
            content = f"[ERROR: Cache file not found: {cache_path}]"
            storage = "cache_missing"
    else:
        # Get inline content
        content = art.get("content")
        storage = "inline"

    output = {
        "success": True,
        "artifact": {
            "id": art.get("id"),
            "name": art.get("name"),
            "source_url": art.get("source-uri"),
            "created_at": art.get("created-at"),
            "content": content,
            "storage": storage,
            "cache_path": cache_path,
            "mime_type": art.get("mime-type"),
            "file_size": art.get("file-size"),
        },
        "entity": None,
    }

    if entity_result:
        ent = entity_result[0]
        output["entity"] = {
            "id": ent.get("id"),
            "name": ent.get("name"),
        }

    print(json.dumps(output, indent=2))

# =============================================================================
# QUERY COMMANDS
# =============================================================================

def cmd_list_entities(args):
    """List all entities."""
    with get_driver() as driver:
        with driver.transaction(TYPEDB_DATABASE, TransactionType.READ) as tx:
            query = f"""match
                $e isa {ENTITY_TYPE};
            fetch {{ "id": $e.id, "name": $e.name, "created-at": $e.created-at }};"""
            results = list(tx.query(query).resolve())

    entities = []
    for r in results:
        entities.append(
            {
                "id": r.get("id"),
                "name": r.get("name"),
                "created_at": r.get("created-at"),
            }
        )

    print(json.dumps({"success": True, "entities": entities, "count": len(entities)}, indent=2))

def cmd_show_entity(args):
    """Get entity details."""
    with get_driver() as driver:
        with driver.transaction(TYPEDB_DATABASE, TransactionType.READ) as tx:
            query = f'''match
                $e isa {ENTITY_TYPE}, has id "{args.id}";
            fetch {{ "id": $e.id, "name": $e.name, "description": $e.description, "created-at": $e.created-at }};'''
            result = list(tx.query(query).resolve())

            if not result:
                print(json.dumps({"success": False, "error": "Entity not found"}))
                return

            # Get notes
            notes_query = f'''match
                $e isa {ENTITY_TYPE}, has id "{args.id}";
                (note: $n, subject: $e) isa aboutness;
            fetch {{ "id": $n.id, "name": $n.name, "content": $n.content }};'''
            notes_result = list(tx.query(notes_query).resolve())

            # Get tags
            tags_query = f'''match
                $e isa {ENTITY_TYPE}, has id "{args.id}";
                (tagged-entity: $e, tag: $t) isa tagging;
            fetch {{ "name": $t.name }};'''
            tags_result = list(tx.query(tags_query).resolve())

    output = {
        "success": True,
        "entity": result[0],
        "notes": notes_result,
        "tags": [t.get("name") for t in tags_result],
    }

    print(json.dumps(output, indent=2, default=str))

# =============================================================================
# UPDATE COMMANDS
# =============================================================================

def cmd_add_note(args):
    """Create a note about an entity."""
    note_id = args.id or generate_id("note")
    timestamp = get_timestamp()

    query = f'''insert $n isa note,
        has id "{note_id}",
        has content "{escape_string(args.content)}",
        has created-at {timestamp}'''

    if args.name:
        query += f', has name "{escape_string(args.name)}"'
    if args.confidence:
        query += f", has confidence {args.confidence}"

    query += ";"

    with get_driver() as driver:
        with driver.transaction(TYPEDB_DATABASE, TransactionType.WRITE) as tx:
            tx.query(query).resolve()
            tx.commit()

        with driver.transaction(TYPEDB_DATABASE, TransactionType.WRITE) as tx:
            about_query = f'''match
                $n isa note, has id "{note_id}";
                $s isa entity, has id "{args.about}";
            insert (note: $n, subject: $s) isa aboutness;'''
            tx.query(about_query).resolve()
            tx.commit()

        if args.tags:
            for tag_name in args.tags:
                tag_id = generate_id("tag")
                with driver.transaction(TYPEDB_DATABASE, TransactionType.READ) as tx:
                    tag_check = f'match $t isa tag, has name "{tag_name}"; fetch {{ "id": $t.id }};'
                    existing_tag = list(tx.query(tag_check).resolve())

                if not existing_tag:
                    with driver.transaction(TYPEDB_DATABASE, TransactionType.WRITE) as tx:
                        tx.query(
                            f'insert $t isa tag, has id "{tag_id}", has name "{tag_name}";'
                        ).resolve()
                        tx.commit()

                with driver.transaction(TYPEDB_DATABASE, TransactionType.WRITE) as tx:
                    tx.query(f'''match
                        $n isa note, has id "{note_id}";
                        $t isa tag, has name "{tag_name}";
                    insert (tagged-entity: $n, tag: $t) isa tagging;''').resolve()
                    tx.commit()

    print(json.dumps({"success": True, "note_id": note_id, "about": args.about}))

def cmd_tag(args):
    """Tag an entity."""
    with get_driver() as driver:
        tag_id = generate_id("tag")
        with driver.transaction(TYPEDB_DATABASE, TransactionType.READ) as tx:
            tag_check = f'match $t isa tag, has name "{args.tag}"; fetch {{ "id": $t.id }};'
            existing_tag = list(tx.query(tag_check).resolve())

        if not existing_tag:
            with driver.transaction(TYPEDB_DATABASE, TransactionType.WRITE) as tx:
                tx.query(f'insert $t isa tag, has id "{tag_id}", has name "{args.tag}";').resolve()
                tx.commit()

        with driver.transaction(TYPEDB_DATABASE, TransactionType.WRITE) as tx:
            tx.query(f'''match
                $e isa entity, has id "{args.entity}";
                $t isa tag, has name "{args.tag}";
            insert (tagged-entity: $e, tag: $t) isa tagging;''').resolve()
            tx.commit()

    print(json.dumps({"success": True, "entity": args.entity, "tag": args.tag}))

def cmd_search_tag(args):
    """Search entities by tag."""
    with get_driver() as driver:
        with driver.transaction(TYPEDB_DATABASE, TransactionType.READ) as tx:
            query = f'''match
                $t isa tag, has name "{args.tag}";
                (tagged-entity: $e, tag: $t) isa tagging;
            fetch {{ "id": $e.id, "name": $e.name }};'''
            results = list(tx.query(query).resolve())

    print(
        json.dumps(
            {
                "success": True,
                "tag": args.tag,
                "entities": results,
                "count": len(results),
            },
            indent=2,
            default=str,
        )
    )

# =============================================================================
# MAIN
# =============================================================================

def main():
    # Infrastructure check — fast-fails with helpful message if TypeDB/dashboard missing
    check_infrastructure(
        skill_name="DOMAIN",                      # replace with actual skill name
        schema_check_type="DOMAIN-main-entity",   # replace: first entity in schema.tql
        has_dashboard=False,                      # set True if skill has dashboard/
        zip_name="domain-v1.0.zip",               # replace: from skill.yaml bundle.zip_name
    )

    parser = argparse.ArgumentParser(
        description="[DOMAIN] CLI - [Brief description]"
    )
    subparsers = parser.add_subparsers(dest="command", help="Command to run")

    # ingest
    p = subparsers.add_parser("ingest", help="Fetch content from URL and store as artifact")
    p.add_argument("--url", required=True, help="Source URL")
    p.add_argument("--tags", nargs="+", help="Tags to apply")

    # add-entity
    p = subparsers.add_parser("add-entity", help="Add an entity manually")
    p.add_argument("--name", required=True, help="Entity name")
    p.add_argument("--description", help="Description")
    p.add_argument("--id", help="Specific ID")

    # list-artifacts
    p = subparsers.add_parser("list-artifacts", help="List artifacts by status")
    p.add_argument(
        "--status",
        choices=["raw", "analyzed", "all"],
        help="Filter: raw, analyzed, or all",
    )

    # show-artifact
    p = subparsers.add_parser("show-artifact", help="Get artifact content")
    p.add_argument("--id", required=True, help="Artifact ID")

    # list-entities
    subparsers.add_parser("list-entities", help="List all entities")

    # show-entity
    p = subparsers.add_parser("show-entity", help="Get entity details")
    p.add_argument("--id", required=True, help="Entity ID")

    # add-note
    p = subparsers.add_parser("add-note", help="Create a note")
    p.add_argument("--about", required=True, help="Entity ID this note is about")
    p.add_argument("--content", required=True, help="Note content")
    p.add_argument("--name", help="Note title")
    p.add_argument("--confidence", type=float, help="Confidence score (0.0-1.0)")
    p.add_argument("--tags", nargs="+", help="Tags to apply")
    p.add_argument("--id", help="Specific ID")

    # tag
    p = subparsers.add_parser("tag", help="Tag an entity")
    p.add_argument("--entity", required=True, help="Entity ID")
    p.add_argument("--tag", required=True, help="Tag name")

    # search-tag
    p = subparsers.add_parser("search-tag", help="Search by tag")
    p.add_argument("--tag", required=True, help="Tag to search for")

    args = parser.parse_args()

    if not TYPEDB_AVAILABLE:
        print(json.dumps({"success": False, "error": "typedb-driver not installed"}))
        sys.exit(1)

    if not args.command:
        parser.print_help()
        sys.exit(1)

    commands = {
        "ingest": cmd_ingest,
        "add-entity": cmd_add_entity,
        "list-artifacts": cmd_list_artifacts,
        "show-artifact": cmd_show_artifact,
        "list-entities": cmd_list_entities,
        "show-entity": cmd_show_entity,
        "add-note": cmd_add_note,
        "tag": cmd_tag,
        "search-tag": cmd_search_tag,
    }

    try:
        commands[args.command](args)
    except Exception as e:
        print(json.dumps({"success": False, "error": str(e)}))
        import traceback

        traceback.print_exc(file=sys.stderr)
        sys.exit(1)

if __name__ == "__main__":
    main()
```

## File: skills/_template/USAGE.md
size: 8642
sha: e937b86449b8fb27e213bccd5502063edc688a1d
upstream: https://github.com/sciknow-io/skillful-alhazen/blob/main/skills/_template/USAGE.md

````text
# Your Domain Name — Usage Reference

## Web Interface

<!-- Optional: remove this section if this skill has no dashboard -->

A Next.js dashboard is available at `http://localhost:3000/<your-domain>` when running `make dashboard-dev`.

**Start the dashboard:**
```bash
make dashboard-dev    # starts on http://localhost:3000
```

**Views:**
- **[View Name]** (`/<your-domain>`) — Description of the main view
- **[Item Detail]** (`/<your-domain>/item/{id}`) — Full detail page for a single item

**Internal organization** (for contributors):
- Pages: `dashboard/src/app/(<your-domain>)/<your-domain>/`
- Components: `dashboard/src/components/<your-domain>/`
- API routes: `dashboard/src/app/api/<your-domain>/`
- TypeScript wrapper: `dashboard/src/lib/<your-domain>.ts`

---

## Ingestion Commands

### Ingest from URL

**Triggers:** "add [item]", "ingest", "fetch", "new [item]"

```bash
uv run python .claude/skills/<your-domain>/<your-domain>.py ingest \
    --url "https://example.com/item" \
    --tags "tag1" "tag2"
```

**Options:**
- `--url` (required): Source URL
- `--tags`: Space-separated tags

**Returns:**
```json
{
  "success": true,
  "artifact_id": "artifact-abc123",
  "entity_id": "entity-xyz789",
  "status": "raw",
  "message": "Artifact stored - ask Claude to 'analyze this' for sensemaking."
}
```

### Add Entity Manually

```bash
uv run python .claude/skills/<your-domain>/<your-domain>.py add-entity \
    --name "Entity Name" \
    --description "Description"
```

---

## Sensemaking Workflow

**When user says "analyze [entity]" or "make sense of [artifact]":**

1. **Get the artifact content**
   ```bash
   uv run python .claude/skills/<your-domain>/<your-domain>.py show-artifact --id "artifact-xyz"
   ```

2. **Read and comprehend the content**
   - Look for: [list key things to extract]
   - Identify: [list entities to create]
   - Note: [list observations to make]

3. **Create/update related entities**
   ```bash
   uv run python .claude/skills/<your-domain>/<your-domain>.py add-entity \
       --name "Extracted Entity" \
       --description "..."
   ```

4. **Create fragments for key pieces**
   ```bash
   uv run python .claude/skills/<your-domain>/<your-domain>.py add-fragment \
       --artifact "artifact-xyz" \
       --content "Extracted piece"
   ```

5. **Create analysis notes**
   ```bash
   uv run python .claude/skills/<your-domain>/<your-domain>.py add-note \
       --about "entity-xyz" \
       --type "analysis" \
       --content "Claude's interpretation and insights..."
   ```

6. **Flag uncertainties** with "uncertain" tag

7. **Report findings to user**
   - Summary of what was found
   - Key insights
   - Suggested next steps

---

## Query Commands

### List Entities

```bash
uv run python .claude/skills/<your-domain>/<your-domain>.py list-entities
uv run python .claude/skills/<your-domain>/<your-domain>.py list-entities --status "active"
```

### Show Entity Details

```bash
uv run python .claude/skills/<your-domain>/<your-domain>.py show-entity --id "entity-xyz"
```

### List Artifacts

```bash
# Show artifacts needing analysis
uv run python .claude/skills/<your-domain>/<your-domain>.py list-artifacts --status raw

# Show all artifacts
uv run python .claude/skills/<your-domain>/<your-domain>.py list-artifacts --status all
```

---

## Update Commands

### Update Status

```bash
uv run python .claude/skills/<your-domain>/<your-domain>.py update-status \
    --entity "entity-xyz" \
    --status "active"
```

### Add Note

```bash
uv run python .claude/skills/<your-domain>/<your-domain>.py add-note \
    --about "entity-xyz" \
    --type "research" \
    --content "Note content here"
```

### Tag Entity

```bash
uv run python .claude/skills/<your-domain>/<your-domain>.py tag \
    --entity "entity-xyz" \
    --tag "important"
```

---

## Data Model

### Entity Types

| Type | Description |
|------|-------------|
| `<domain>-entity` | Primary thing you track |
| `<domain>-artifact` | Raw captured content |
| `<domain>-fragment` | Extracted piece |
| `<domain>-note` | Claude's analysis |

### Attributes

| Attribute | Type | Description |
|-----------|------|-------------|
| `attribute-1` | string | Description |
| `attribute-2` | datetime | Description |

### Relations

| Relation | Description |
|----------|-------------|
| `relation-1` | How entities connect |

---

## Command Reference

| Command | Description | Key Args |
|---------|-------------|----------|
| `ingest` | Fetch and store raw content | `--url` |
| `add-entity` | Create entity manually | `--name` |
| `add-note` | Create a note | `--about`, `--type`, `--content` |
| `list-entities` | List all entities | `--status` |
| `show-entity` | Get entity details | `--id` |
| `list-artifacts` | List artifacts | `--status` |
| `show-artifact` | Get artifact content | `--id` |
| `update-status` | Change entity status | `--entity`, `--status` |
| `tag` | Tag an entity | `--entity`, `--tag` |
| `search-tag` | Find by tag | `--tag` |

---

## Analysis Workflow

The Analysis phase turns accumulated sensemaking notes into structured, versioned, re-runnable insights. All curation skills use the **LinkML -> Pydantic -> Hamilton** pattern:

### 1. Define your schema (LinkML)

Copy `schema/eval_schema_template.yaml` and rename it for your domain. Fill in:
- Your **dimension names** in `DimensionScores` (rename `dimension_a`, `dimension_b`, etc.)
- Your **entity categories** in the `EntityCategory` enum
- Add optional fields freely — they default to `None`, keeping old records valid

### 2. Implement Pydantic models

Create `eval_models.py` next to your skill script. Mirror the LinkML schema as Pydantic v2:

```python
from pydantic import BaseModel, Field, model_validator
from typing import Annotated, Optional
from enum import Enum

Score = Annotated[int, Field(ge=0, le=3)]

class DimensionScores(BaseModel):
    dimension_a: Score
    dimension_b: Score
    total: int = 0

    @model_validator(mode="after")
    def compute_total(self) -> "DimensionScores":
        self.total = self.dimension_a + self.dimension_b
        return self

class EntityAssessment(BaseModel):
    id: str
    name: str
    scores: DimensionScores
    assessment_summary: Optional[str] = None
    parse_warnings: list[str] = []
```

Generate JSON Schema for documentation:
```bash
uv run python eval_models.py > schema/<skill>_schema.json
```

### 3. Write a Hamilton pipeline

Copy `pipelines/pipeline_template.py` and adapt:
- `fetch_records(investigation_id)` — TypeQL query for your entities + assessment notes
- `parse_records(fetch_records)` — keyword matching on your dimension labels
- `table_data()` — serialises to JSON (no changes needed)
- `plot_code()` — replace the placeholder with your Observable Plot expression

**The sensemaking agent must write structured score tables** in assessment notes using this format so the parser can extract scores:

```markdown
| Criterion | Score (0-3) | Notes |
|---|---|---|
| Dimension A label | 2 | explanation |
| Dimension B label | 1 | explanation |
```

### 4. Register the pipeline in TypeDB

```bash
uv run python .claude/skills/<skill>/<skill>.py add-pipeline \
  --investigation <ID> \
  --title "My Analysis" \
  --analysis-type pipeline-plot \
  --pipeline-script "@skills/<skill>/pipelines/pipeline_name.py" \
  --pipeline-config '{"outputs":["plot_code","table_data"],"inputs":{"investigation_id":"<ID>"},"env_inputs":{}}'
```

### 5. Run the pipeline

```bash
uv run python .claude/skills/<skill>/<skill>.py run-pipeline --id <analysis-id>
```

Re-run any time new sensemaking notes are added — the pipeline reads from TypeDB and re-generates outputs.

### 6. View in dashboard

Navigate to the Analysis tab of your investigation page. The heatmap renders immediately using the pre-computed `table_data` stored in TypeDB.

### Schema Evolution

Adding new analysis dimensions later:
1. Add `Optional` field to LinkML YAML and Pydantic model (new field = no migration)
2. Re-run the pipeline — existing records get `None`/0 for the new field
3. Update the sensemaking prompt to score the new dimension in future notes

---

## TypeDB Reference

When writing custom queries, consult:

- **This Skill's Schema:** `local_skills/<your-domain>/schema.tql`
- **Core Schema:** `local_resources/typedb/alhazen_notebook.tql`

### Common Pitfalls (TypeDB 3.x)

- **Fetch syntax** — Use `fetch { "key": $var.attr };` (JSON-style, NOT `fetch $var: attr1;`)
- **No sessions** — Use `driver.transaction(database, TransactionType.X)` directly
- **Update = delete + insert** — Can't modify attributes in place
````
