ontotwin-atlas-mapping

name	ontotwin-atlas-mapping
description	Use when Claude Code is mapping a real ontology corpus into the OntoTwin atlas manifest, adapters, groups, labels, lenses, counts, search, or tile APIs.

OntoTwin Atlas Mapping

Use this project skill when the task affects ontology-to-atlas mapping: manifest fields, group hierarchy, labels, aliases, count semantics, search targets, tiles, lasso, table, export, vectors, graph/projection artifacts, or production adapter wiring.

Portability level: harness-specific. The mapping checklist is portable, but the invocation examples, .claude/skills/ location, and subagent names are Claude Code project conventions.

FPF Grounding

Before spec-sensitive work, check the active FPF runtime with get_fpf_index_status or the available FPF MCP equivalent. Stop and report the missing access if no FPF runtime or generated spec docs are available.

Prefer the fpf-memory-mcp skill when available. Use available runtime tools such as get_fpf_index_status and query_fpf_spec; do not invent FPF selectors or canonical wording from memory.

Use these FPF selectors:

• A.7: keep role, method, work, status, description, and specification distinct.
• A.15: keep method descriptions and actual performed work distinct.
• E.10: keep promise, ability, performance, work, and evidence terminology distinct.
• E.10.D2: keep intension, description, and specification layers separate.
• F.18: name local context, reference plane, time/version, and bridge/mapping explicitly.

Required Reading

Read these before editing:

• docs/atlas-adapter-contract.md
• docs/production-manifest-schema.md
• docs/atlas-configuration-boundaries.md
• docs/graph-tile-atlas-strategy.md
• docs/adoption-decision-framework.md
• docs/lens-options.md
• src/atlasManifest.js
• src/memberAtlas.js
• src/atlasLookup.js
• src/atlasInteraction.js

Mapping Model

Preserve this separation:

Layer	Atlas meaning	Do not confuse with
Thing	source ontology document, concept, member, or approved aggregate unit	map label or UI component
Description	display name, alias, tooltip, summary, metadata description	source truth or production evidence
Specification	manifest, adapter type, API contract, disclosure rule, behavior rule	actual API response or performed work
Work	embedding job, graph job, projection job, tile publication, browser interaction	method description or plan
Evidence	metrics, tests, domain review, schema validation, browser proof	promise, intent, or visual resemblance

Default point unit is one ontology document. Any aggregate point mode must be declared in the manifest with count_weight, aggregation rule, expansion route, count source, and disclosure policy.

Manifest Requirements

Require these fields or an explicit stop/replan note:

REPLACE_WITH_... values are placeholders. Do not treat a copied skeleton as enabled production governance. Replace placeholders only with client-safe public policy handles or non-sensitive status enums. Keep server-only approval IDs, owner IDs, ticket IDs, topology details, and retention records in server governance artifacts, not in the browser-fetched manifest.

Retention and deployment-gate values are closed affirmative public-status enums. Copied generic status strings or denied approval states must fail closed; do not invent substitute status labels during mapping.

Retention period fields are client-safe public policy handles, not server-only retention records. Production manifests must bind logs_period, exports_period, and screenshots_period before protected workflows can enable.

The top-level disclosure_policy_id, privacy.disclosure_policy_id, and privacy.count_disclosure.policy_id must resolve to one client-safe policy handle. count_response_shape is a closed six-field response contract, not an extensible display hint.

{
  "atlas_version": "atlas_2026_05_31",
  "corpus_snapshot_id": "ontology_snapshot_2026_05",
  "representation": {
    "point_unit": "ontology_document",
    "coordinate_space": "projected_atlas_xy",
    "count_weight_default": 1,
    "aggregate_expansion_api": null,
    "aggregate_expansion_behavior": "not_applicable_non_aggregate"
  },
  "artifacts": {
    "embedding_id": "embedding_model_snapshot",
    "graph_id": "ann_graph_version",
    "projection_id": "projection_version",
    "tile_pyramid_id": "tile_pyramid_version"
  },
  "source_field_mapping": [
    {"source_field": "source_record_identifier", "manifest_field": "record_id", "api_field": "detail_table", "public_tile_exposure": "forbidden"},
    {"source_field": "family_topic_cohort", "manifest_field": "groups[]", "api_field": "search_filter_table", "public_tile_exposure": "opaque_token_only"},
    {"source_field": "label_title", "manifest_field": "labels[]", "api_field": "label_search", "public_tile_exposure": "opaque_token_only"},
    {"source_field": "embedding_artifact", "manifest_field": "artifacts.embedding_id", "api_field": "manifest_detail_metadata", "public_tile_exposure": "forbidden"},
    {"source_field": "projected_coordinate", "manifest_field": "tile.x_y", "api_field": "tile", "public_tile_exposure": "render_safe"},
    {"source_field": "count_value", "manifest_field": "count.value", "api_field": "tile_lasso_table_export", "public_tile_exposure": "disclosure_policy_only"}
  ],
  "privacy": {
    "disclosure_policy_id": "REPLACE_WITH_DISCLOSURE_POLICY_ID",
    "public_tiles": "render_safe_only",
    "tile_service_scope": "public_render_safe",
    "public_tile_tokens": {
      "group": "opaque_render_token",
      "label": "opaque_render_token",
      "style": "opaque_render_token",
      "source_group_ids": "not_allowed_in_public_tiles",
      "source_label_ids": "not_allowed_in_public_tiles"
    },
    "count_disclosure": {
      "policy_id": "REPLACE_WITH_DISCLOSURE_POLICY_ID",
      "mode": "suppression",
      "parameters_source": "REPLACE_WITH_APPROVED_DEPLOYMENT_POLICY_ID",
      "min_cell_size": "REPLACE_WITH_MIN_CELL_SIZE_OR_NOT_APPLICABLE",
      "rounding_interval": "REPLACE_WITH_ROUNDING_INTERVAL_OR_NOT_APPLICABLE",
      "noise_mode": "REPLACE_WITH_NOISE_MODE_OR_NOT_APPLICABLE",
      "allowed_exact_count_roles": [],
      "audit_required": true,
      "export_limits": "REPLACE_WITH_APPROVED_EXPORT_POLICY_ID"
    }
  },
  "api": {
    "tiles": "/api/atlas/atlas_2026_05_31/tiles",
    "search": "/api/atlas/atlas_2026_05_31/search",
    "records": "/api/atlas/atlas_2026_05_31/records",
    "table": "/api/atlas/atlas_2026_05_31/table",
    "lasso": "/api/atlas/atlas_2026_05_31/lasso",
    "session_access": "/api/atlas/atlas_2026_05_31/session-access",
    "exports": "/api/atlas/atlas_2026_05_31/exports"
  },
  "access_control": {
    "auth_state": "requires_authenticated_session",
    "authorization_state": "requires_authorized_session",
    "tile_service_auth": "public_render_safe",
    "detail_table_lasso_export_auth": "live_authorization_required",
    "production_behavior": "fail_closed_when_missing_or_unauthorized"
  },
  "audit": {
    "required_events": ["record_detail", "table", "lasso", "export", "exact_count"],
    "log_redaction": "no_raw_text_no_embeddings_no_protected_metadata",
    "screenshot_policy": "no_sensitive_tiles_or_details_without_approval"
  },
  "cache": {
    "public_tile_cacheability": "render_safe_only",
    "protected_response_cacheability": "no_store",
    "cache_key_redaction": "no_identifiers_or_sensitive_query_text"
  },
  "retention": {
    "owner": "retention_owner_assigned",
    "logs": "retention_logs_configured",
    "exports": "retention_exports_configured",
    "screenshots": "retention_screenshots_configured",
    "logs_period": "retention_logs_period_policy_bound",
    "exports_period": "retention_exports_period_policy_bound",
    "screenshots_period": "retention_screenshots_period_policy_bound"
  },
  "deployment_gate": {
    "hosting_topology": "hosting_topology_reviewed",
    "data_residency": "data_residency_reviewed",
    "observability": "observability_configured",
    "cost_owner": "cost_owner_assigned",
    "support_owner": "support_owner_assigned",
    "legal_approval": "legal_approved",
    "security_approval": "security_approved",
    "privacy_approval": "privacy_approved",
    "operations_approval": "operations_approved"
  },
  "publicTileSchema": {
    "allowed_fields": ["tile_point_id", "x", "y", "style_token", "group_token", "label_token", "aggregate_count"],
    "forbidden_fields": [
      "id",
      "record_id",
      "recordId",
      "display_id",
      "displayId",
      "member_id",
      "memberId",
      "group_id",
      "groupId",
      "label_id",
      "labelId",
      "source_group_id",
      "sourceGroupId",
      "source_label_id",
      "sourceLabelId",
      "source_query_text",
      "sourceQueryText",
      "raw_text",
      "rawText",
      "protected_metadata",
      "protectedMetadata",
      "embedding",
      "exact_small_count",
      "exactSmallCount"
    ],
    "production_behavior": "validate_before_publish"
  },
  "count_semantics": ["exact", "aggregate", "sampled", "estimated", "loaded_tile"],
  "count_response_shape": ["value", "source", "method", "disclosure_policy_id", "privacy_transform", "exactness_scope"],
  "groups": [
    { "group_id": "topic:example", "kind": "topic", "label": "Example topic", "search_terms": ["example topic"] }
  ],
  "labels": [
    { "label_id": "label:example-topic", "target_group_id": "topic:example", "group_id": "topic:example", "short_map_label": "Example" }
  ],
  "color_modes": [
    { "id": "ontology", "label": "Ontology" }
  ],
  "search": {
    "identifier_first": true,
    "record_identifier_patterns": ["REPLACE_WITH_RECORD_IDENTIFIER_REGEX"],
    "supported_targets": ["record", "group", "region", "multi_region", "none"],
    "implemented_targets": ["record", "group", "none"],
    "production_target_contract": ["record", "group", "region", "multi_region", "none"]
  }
}

aggregate_expansion_api is required only for aggregate point modes. For one ontology document per point, keep it null and declare aggregate_expansion_behavior: "not_applicable_non_aggregate".

display_id is optional. If the source corpus has a display alias, add it to source_field_mapping[] with public_tile_exposure: "forbidden" and keep it out of public tiles.

Authenticated-internal tile services may use public_tile_exposure: "authenticated_internal_only" for record_id, groups[], or labels[] only when privacy.public_tiles, privacy.tile_service_scope, and access_control.tile_service_auth all declare authenticated_internal and publicTileSchema.allowed_fields explicitly names the matching tile field such as record_id, source_group_id, or source_label_id. Public render-safe tiles must keep canonical/source identifiers forbidden or tokenized.

For production protected workflows, the manifest declares access requirements and the app shell supplies live session access. The accepted runtime session state is auth_state: "authenticated", authorization_state: "authorized", and detail_table_lasso_export_auth: "authorized". Empty groups, labels, or color_modes arrays are not readiness-valid.

Group entries must use lookup-compatible group_id, kind, label, and non-empty search_terms fields. Supported group kinds are family, topic, subtopic, cohort, and record. Label entries must include label_id, a group_id or target_group_id, and a renderable short label.

Public render-safe tiles must declare tile_point_id, x, y, style_token, and group_token. label_token and aggregate_count are allowed optional fields and should not be required by the readiness gate.

Do not hard-code production ontology groups, labels, aliases, colors, field visibility, count semantics, or behavior rules in React components. Put them in the manifest or adapter responses.

Tile And API Rules

Public or broadly cacheable point tiles may contain only:

• tile-local opaque ID
• x/y coordinates in the declared coordinate space
• opaque style token or opaque group token
• optional opaque short label token
• privacy-filtered aggregate count fields

Keep these behind secured detail, table, lasso, export, or authenticated internal APIs:

• canonical record IDs
• display/member IDs
• source group IDs
• source label IDs
• raw text
• protected metadata
• embeddings
• rich details
• exact small-cohort counts

Search returns typed targets only:

• record
• group
• region
• multi_region
• none

The atlas finder must not pretend to answer free-form analyst questions unless a separate query system is connected and named in the manifest.

All count-returning production responses must use this uniform shape:

{
  "value": 4200,
  "source": "aggregate",
  "method": "server_refined_lasso_v1",
  "disclosure_policy_id": "REPLACE_WITH_DISCLOSURE_POLICY_ID",
  "privacy_transform": "suppressed",
  "exactness_scope": "aggregate_only"
}

Reject or fail closed on bare numbers, prose-only counts, and counts that bypass the manifest disclosure policy.

Claude Code Route

1. Fill this adoption memo before editing:

Facts:
- point unit:
- corpus snapshot:
- identifier fields:
- embedding artifact:
- graph/projection artifacts:
- protected fields:
- count semantics:
- source-field mapping table:
- auth and authorization state:
- audit/cache/retention policy:

Boundaries:
- ontology fields that must not change:
- fields excluded from public tiles:
- disclosure policy:
- APIs required:
- production-owned jobs:

Fit:
- manifest mapping:
- adapter mapping:
- label/search mapping:
- graph/tile mapping:

Evidence needed:
- schema validation:
- graph/projection metrics:
- tile privacy check:
- search/label regression:
- browser checks:

Stop/replan trigger:

2. Invoke subagents by affected surface:
   • health-ontology-steward for groups, labels, aliases, identifiers, source fields.
   • atlas-adapter-contract-reviewer for manifest, API, tile, search, table, lasso, export.
   • atlas-vector-graph-reviewer for embeddings, graph, projection, clusters, geometry claims.
   • health-privacy-disclosure-reviewer for counts, tiles, lasso, table, export, screenshots.
   • qa-evidence-gate-reviewer for completion claims and proof.
3. Change the adapter/configuration boundary first. Avoid UI rewrites until the mapping contract is explicit.

If Claude Code subagents are unavailable because of auth, quota, model, or tool limits, do not treat a local checklist as subagent approval. Record the blocker, perform a provisional local review by the same interests, and keep the readiness claim open until real subagent review can run.

If autoreview is unavailable because of auth, quota, model, or CLI limits, record the exact command and blocker. Do not claim autoreview clean.

Claude Code Prompt Example

/ontotwin-atlas-mapping

Task: bind the real ontology manifest to the OntoTwin atlas without reshaping the source ontology.

Use active FPF selectors A.7, A.15, E.10, E.10.D2, and F.18.
Separate Thing, Description, Specification, Work, and Evidence.
Represent groups, labels, aliases, colors, count semantics, and behavior rules as manifest configuration.
Keep public tiles render-safe and fail closed when disclosure_policy_id is missing.
Invoke health-ontology-steward, atlas-adapter-contract-reviewer, atlas-vector-graph-reviewer, health-privacy-disclosure-reviewer, and qa-evidence-gate-reviewer before broad edits.

Acceptance Checks

• The manifest adapts to the existing ontology; no source ontology renaming is required.
• Every displayed count declares exact, aggregate, sampled, estimated, or loaded_tile.
• The disclosure policy names job-supplied parameters or explicitly stops before choosing policy defaults.
• Label click resolves to the same typed target as search.
• Search has explicit none or multi_region behavior for unsupported or scattered queries.
• Production geometry claims cite embedding, graph, projection, and metric provenance.
• Public tile validation rejects canonical IDs, protected fields, raw text, raw embeddings, and counts outside disclosure policy.
• Public tile validation rejects source group IDs and source label IDs unless the tile service is authenticated internal data with recorded approval.
• Count-returning production responses use the uniform count response shape.
• A source-field mapping table proves source field -> manifest field -> API field, or the task stops before production wiring.
• Synthetic demo adapters remain behind clearly named synthetic surfaces, and tests prove synthetic recordId/displayId do not become public production tile fields.
• Auth, authorization, audit, cache, retention, screenshot/export, and deployment-gate fields are schema-bound, not prose-only assumptions.
• Current tests/build/browser checks match the changed behavior.