MetaState-Prototype-Project · coodos · Aug 31, 2026 · Aug 31, 2026 · Aug 31, 2026 · Aug 31, 2026
@@ -2,6 +2,8 @@
 
 **[Documentation](https://docs.w3ds.metastate.foundation)** — Getting started with W3DS and the MetaState prototype.
 
+**Building with an AI coding agent?** Load the [W3DS agent skill](https://docs.w3ds.metastate.foundation/docs/Post%20Platform%20Guide/ai-agent-skill) — `npx skills add MetaState-Prototype-Project/prototype@w3ds`, or point a fetch-capable agent at [`/skill/SKILL.md`](https://docs.w3ds.metastate.foundation/skill/SKILL.md) and [`/llms.txt`](https://docs.w3ds.metastate.foundation/llms.txt).
+
 **Quick start (registry + evault-core + dev-sandbox):** see **[QUICKSTART.md](QUICKSTART.md)** — one script to run Postgres + Neo4j in Docker and the core services locally. Dev sandbox runs at **http://localhost:8080**.
 
 ## Docker Development Environment

@@ -203,4 +203,6 @@ The [Provisioner](/docs/W3DS%20Basics/Links) hosts `/provision`; the [Registry](
 - Understand [Authentication](/docs/W3DS%20Protocol/Authentication) - How users authenticate with platforms
 - Learn about [Signing](/docs/W3DS%20Protocol/Signing) - Signature creation and verification
 - Explore [Signature Formats](/docs/W3DS%20Protocol/Signature-Formats) - Technical details on cryptographic signatures
+- Read the [Data Ownership Rules](/docs/W3DS%20Basics/Data-Ownership-Rules) - Where data lives, and why the eVault is the source of truth
 - Build a platform with the [Post Platform Guide](/docs/Post%20Platform%20Guide/getting-started) - Step-by-step guide to creating a W3DS-compatible platform
+- Building with an AI coding agent? Load the [W3DS agent skill](/docs/Post%20Platform%20Guide/ai-agent-skill) first - it keeps the agent grounded in these docs instead of guessing
@@ -24,13 +24,16 @@ Returns a list of all available schemas.
 
 ```json
 [
- { "id": "550e8400-e29b-41d4-a716-446655440000", "title": "User" },
- { "id": "550e8400-e29b-41d4-a716-446655440001", "title": "SocialMediaPost" }
+ { "id": "550e8400-e29b-41d4-a716-446655440000", "title": "User", "domain": "identity" },
+ { "id": "550e8400-e29b-41d4-a716-446655440001", "title": "SocialMediaPost", "domain": "social" }
 ]
 ```
 
 - `id`: Schema W3ID (`schemaId`).
 - `title`: Human-readable schema title.
+- `domain`: The domain the schema belongs to, or `null` if untagged. See [GET /domains](#get-domains).
+
+This endpoint is the only correct way to obtain a `schemaId`. Match on `title`, then confirm the field names with `GET /schemas/:id` before writing a mapping. Schema IDs are not derivable, not sequential, and not stable enough to recall from memory — a wrong `schemaId` means every awareness packet for that type is silently dropped by receiving platforms.
 
 ### GET /schemas/:id
 
@@ -44,6 +47,30 @@ Returns the full JSON Schema for the given W3ID. Use this when you need the comp
 
 - **404**: Schema not found for the given W3ID.
 
+### GET /domains
+
+Returns the domain list every schema is tagged with — the same list a platform is granted access to, one domain at a time.
+
+**Response** (200):
+
+```json
+{
+ "schemaId": "<the Domain schema's own W3ID>",
+ "domains": [
+ { "id": "identity", "label": "Identity", "description": "..." },
+ { "id": "social", "label": "Social", "description": "..." }
+ ]
+}
+```
+
+The list is not a separate config file: it is read from the `Domain` schema's own enum, so it is versioned, browsable and fetchable like any other type.
+
+### GET /domains/:id/schemas
+
+Returns every schema under one domain: `{ "domain": { ... }, "schemas": [ { "id", "title" } ] }`. **404** if the domain does not exist.
+
+Use this when you know the subject area but not the type name — "what does W3DS already have for finance?" — before concluding that nothing fits and [proposing a new ontology](#proposing-a-new-ontology).
+
 ### Human-facing viewer
 
 - **GET /** — Renders a viewer page that lists schemas and supports search. Optional query `?q=...` filters by title or ID; `?schema=<id>` shows one schema.
@@ -83,6 +110,68 @@ Example (conceptually):
 
 In eVault, a MetaEnvelope for a post would have `ontology: "550e8400-e29b-41d4-a716-446655440001"`, and its Envelopes would have `ontology` values such as `content`, `authorId`, `createdAt`.
 
+## Proposing a new ontology
+
+Nothing in W3DS obliges you to squeeze your data into an existing type. If no schema fits what you are modelling, the correct move is to **propose a new one** — never to invent a `schemaId` and ship it.
+
+An invented `schemaId` does not fail loudly. The MetaEnvelope is written, the awareness packet fans out, and every receiving platform finds no mapping for that schema and drops it. The data becomes unreachable to the ecosystem while looking perfectly healthy on the platform that wrote it.
+
+### Before proposing
+
+1. `GET /schemas` and search the titles.
+2. `GET /domains/:id/schemas` for the domain your data belongs to.
+3. Read the near misses in full with `GET /schemas/:id`.
+
+Reuse beats addition, and **extending a near match by PR beats creating a parallel type**. Two schemas that mean the same thing split the ecosystem in half: platforms mapping one will not see data from platforms mapping the other.
+
+### Write the schema
+
+Schemas are ordinary files in the [prototype repository](https://github.com/MetaState-Prototype-Project/prototype), under `services/ontology/schemas/<name>.json`. The service loads the directory into an in-memory index at boot; there is no database and no registration call.
+
+```json
+{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "schemaId": "<a freshly generated random UUIDv4>",
+ "title": "Bookmark",
+ "domain": "productivity",
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "format": "uuid",
+ "description": "The unique identifier for the bookmark"
+ },
+ "userId": {
+ "type": "string",
+ "format": "uuid",
+ "description": "The ID of the user who created the bookmark"
+ },
+ "createdAt": {
+ "type": "string",
+ "format": "date-time",
+ "description": "When the bookmark was created"
+ }
+ },
+ "required": ["id", "userId", "createdAt"],
+ "additionalProperties": false
+}
+```
+
+Requirements:
+
+- **`schemaId`** — a freshly generated random UUIDv4 (`uuidgen`, `crypto.randomUUID()`). Never derive one from an existing ID, never continue a numeric sequence you notice in the directory, and never reuse an ID from another schema.
+- **`title`** — the type name as other platforms will search for it. Singular, PascalCase.
+- **`domain`** — one value from the `Domain` schema's enum, fetchable at `GET /domains`. Platforms are granted access domain by domain, so this decides who can consume the type.
+- **`properties`** — every field with a `description`. Each property name becomes an Envelope's `ontology` value in the eVault, so **name fields for their cross-platform meaning, not after your local columns**. `authorId` is a W3DS field name; `fk_user_id_2` is not.
+- **`required`** — the fields a consumer can rely on being present.
+- **`additionalProperties`** — `false`, unless you have a specific reason.
+
+### Open the PR
+
+Add the file, open a pull request against the prototype repository, and say in the description what the type is for and which platform will write it. Reviewers will ask whether an existing schema could have carried the data — answer that question in the PR body and you will save a round trip.
+
+Until the PR merges and the service redeploys, **the type does not exist**. Do not ship a `mapping.json` referencing an unmerged `schemaId`; the sync will look fine locally and silently drop everywhere else.
+
 ## Available schemas
 
 To see all available schemas, call `GET /schemas` on the [Ontology production service](/docs/W3DS%20Basics/Links) or browse the [viewer](https://ontology.w3ds.metastate.foundation/) at the production base URL.
@@ -97,3 +186,4 @@ To see all available schemas, call `GET /schemas` on the [Ontology production se
 - [eVault](/docs/Infrastructure/eVault) — MetaEnvelopes, Envelopes, and the `ontology` field
 - [W3DS Basics](/docs/W3DS%20Basics/getting-started) — Ontology and schema concepts
 - [Links](/docs/W3DS%20Basics/Links) — Production Ontology base URL
+- [Data Ownership Rules](/docs/W3DS%20Basics/Data-Ownership-Rules) — why every persisted entity needs an ontology
@@ -2,6 +2,8 @@
 
 **[Documentation](https://docs.w3ds.metastate.foundation)** — Getting started with W3DS and the MetaState prototype.
 
+**Building with an AI coding agent?** Load the [W3DS agent skill](https://docs.w3ds.metastate.foundation/docs/Post%20Platform%20Guide/ai-agent-skill) — `npx skills add MetaState-Prototype-Project/prototype@w3ds`, or point a fetch-capable agent at [`/skill/SKILL.md`](https://docs.w3ds.metastate.foundation/skill/SKILL.md) and [`/llms.txt`](https://docs.w3ds.metastate.foundation/llms.txt).
+
 **Quick start (registry + evault-core + dev-sandbox):** see **[QUICKSTART.md](QUICKSTART.md)** — one script to run Postgres + Neo4j in Docker and the core services locally. Dev sandbox runs at **http://localhost:8080**.
 
 ## Docker Development Environment

@@ -203,4 +203,6 @@ The [Provisioner](/docs/W3DS%20Basics/Links) hosts `/provision`; the [Registry](
 - Understand [Authentication](/docs/W3DS%20Protocol/Authentication) - How users authenticate with platforms
 - Learn about [Signing](/docs/W3DS%20Protocol/Signing) - Signature creation and verification
 - Explore [Signature Formats](/docs/W3DS%20Protocol/Signature-Formats) - Technical details on cryptographic signatures
+- Read the [Data Ownership Rules](/docs/W3DS%20Basics/Data-Ownership-Rules) - Where data lives, and why the eVault is the source of truth
 - Build a platform with the [Post Platform Guide](/docs/Post%20Platform%20Guide/getting-started) - Step-by-step guide to creating a W3DS-compatible platform
+- Building with an AI coding agent? Load the [W3DS agent skill](/docs/Post%20Platform%20Guide/ai-agent-skill) first - it keeps the agent grounded in these docs instead of guessing
@@ -24,13 +24,16 @@ Returns a list of all available schemas.
 
 ```json
 [
- { "id": "550e8400-e29b-41d4-a716-446655440000", "title": "User" },
- { "id": "550e8400-e29b-41d4-a716-446655440001", "title": "SocialMediaPost" }
+ { "id": "550e8400-e29b-41d4-a716-446655440000", "title": "User", "domain": "identity" },
+ { "id": "550e8400-e29b-41d4-a716-446655440001", "title": "SocialMediaPost", "domain": "social" }
 ]
 ```
 
 - `id`: Schema W3ID (`schemaId`).
 - `title`: Human-readable schema title.
+- `domain`: The domain the schema belongs to, or `null` if untagged. See [GET /domains](#get-domains).
+
+This endpoint is the only correct way to obtain a `schemaId`. Match on `title`, then confirm the field names with `GET /schemas/:id` before writing a mapping. Schema IDs are not derivable, not sequential, and not stable enough to recall from memory — a wrong `schemaId` means every awareness packet for that type is silently dropped by receiving platforms.
 
 ### GET /schemas/:id
 
@@ -44,6 +47,30 @@ Returns the full JSON Schema for the given W3ID. Use this when you need the comp
 
 - **404**: Schema not found for the given W3ID.
 
+### GET /domains
+
+Returns the domain list every schema is tagged with — the same list a platform is granted access to, one domain at a time.
+
+**Response** (200):
+
+```json
+{
+ "schemaId": "<the Domain schema's own W3ID>",
+ "domains": [
+ { "id": "identity", "label": "Identity", "description": "..." },
+ { "id": "social", "label": "Social", "description": "..." }
+ ]
+}
+```
+
+The list is not a separate config file: it is read from the `Domain` schema's own enum, so it is versioned, browsable and fetchable like any other type.
+
+### GET /domains/:id/schemas
+
+Returns every schema under one domain: `{ "domain": { ... }, "schemas": [ { "id", "title" } ] }`. **404** if the domain does not exist.
+
+Use this when you know the subject area but not the type name — "what does W3DS already have for finance?" — before concluding that nothing fits and [proposing a new ontology](#proposing-a-new-ontology).
+
 ### Human-facing viewer
 
 - **GET /** — Renders a viewer page that lists schemas and supports search. Optional query `?q=...` filters by title or ID; `?schema=<id>` shows one schema.
@@ -83,6 +110,68 @@ Example (conceptually):
 
 In eVault, a MetaEnvelope for a post would have `ontology: "550e8400-e29b-41d4-a716-446655440001"`, and its Envelopes would have `ontology` values such as `content`, `authorId`, `createdAt`.
 
+## Proposing a new ontology
+
+Nothing in W3DS obliges you to squeeze your data into an existing type. If no schema fits what you are modelling, the correct move is to **propose a new one** — never to invent a `schemaId` and ship it.
+
+An invented `schemaId` does not fail loudly. The MetaEnvelope is written, the awareness packet fans out, and every receiving platform finds no mapping for that schema and drops it. The data becomes unreachable to the ecosystem while looking perfectly healthy on the platform that wrote it.
+
+### Before proposing
+
+1. `GET /schemas` and search the titles.
+2. `GET /domains/:id/schemas` for the domain your data belongs to.
+3. Read the near misses in full with `GET /schemas/:id`.
+
+Reuse beats addition, and **extending a near match by PR beats creating a parallel type**. Two schemas that mean the same thing split the ecosystem in half: platforms mapping one will not see data from platforms mapping the other.
+
+### Write the schema
+
+Schemas are ordinary files in the [prototype repository](https://github.com/MetaState-Prototype-Project/prototype), under `services/ontology/schemas/<name>.json`. The service loads the directory into an in-memory index at boot; there is no database and no registration call.
+
+```json
+{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "schemaId": "<a freshly generated random UUIDv4>",
+ "title": "Bookmark",
+ "domain": "productivity",
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "format": "uuid",
+ "description": "The unique identifier for the bookmark"
+ },
+ "userId": {
+ "type": "string",
+ "format": "uuid",
+ "description": "The ID of the user who created the bookmark"
+ },
+ "createdAt": {
+ "type": "string",
+ "format": "date-time",
+ "description": "When the bookmark was created"
+ }
+ },
+ "required": ["id", "userId", "createdAt"],
+ "additionalProperties": false
+}
+```
+
+Requirements:
+
+- **`schemaId`** — a freshly generated random UUIDv4 (`uuidgen`, `crypto.randomUUID()`). Never derive one from an existing ID, never continue a numeric sequence you notice in the directory, and never reuse an ID from another schema.
+- **`title`** — the type name as other platforms will search for it. Singular, PascalCase.
+- **`domain`** — one value from the `Domain` schema's enum, fetchable at `GET /domains`. Platforms are granted access domain by domain, so this decides who can consume the type.
+- **`properties`** — every field with a `description`. Each property name becomes an Envelope's `ontology` value in the eVault, so **name fields for their cross-platform meaning, not after your local columns**. `authorId` is a W3DS field name; `fk_user_id_2` is not.
+- **`required`** — the fields a consumer can rely on being present.
+- **`additionalProperties`** — `false`, unless you have a specific reason.
+
+### Open the PR
+
+Add the file, open a pull request against the prototype repository, and say in the description what the type is for and which platform will write it. Reviewers will ask whether an existing schema could have carried the data — answer that question in the PR body and you will save a round trip.
+
+Until the PR merges and the service redeploys, **the type does not exist**. Do not ship a `mapping.json` referencing an unmerged `schemaId`; the sync will look fine locally and silently drop everywhere else.
+
 ## Available schemas
 
 To see all available schemas, call `GET /schemas` on the [Ontology production service](/docs/W3DS%20Basics/Links) or browse the [viewer](https://ontology.w3ds.metastate.foundation/) at the production base URL.
@@ -97,3 +186,4 @@ To see all available schemas, call `GET /schemas` on the [Ontology production se
 - [eVault](/docs/Infrastructure/eVault) — MetaEnvelopes, Envelopes, and the `ontology` field
 - [W3DS Basics](/docs/W3DS%20Basics/getting-started) — Ontology and schema concepts
 - [Links](/docs/W3DS%20Basics/Links) — Production Ontology base URL
+- [Data Ownership Rules](/docs/W3DS%20Basics/Data-Ownership-Rules) — why every persisted entity needs an ontology
@@ -2,6 +2,8 @@
 
 **[Documentation](https://docs.w3ds.metastate.foundation)** — Getting started with W3DS and the MetaState prototype.
 
+**Building with an AI coding agent?** Load the [W3DS agent skill](https://docs.w3ds.metastate.foundation/docs/Post%20Platform%20Guide/ai-agent-skill) — `npx skills add MetaState-Prototype-Project/prototype@w3ds`, or point a fetch-capable agent at [`/skill/SKILL.md`](https://docs.w3ds.metastate.foundation/skill/SKILL.md) and [`/llms.txt`](https://docs.w3ds.metastate.foundation/llms.txt).
+
 **Quick start (registry + evault-core + dev-sandbox):** see **[QUICKSTART.md](QUICKSTART.md)** — one script to run Postgres + Neo4j in Docker and the core services locally. Dev sandbox runs at **http://localhost:8080**.
 
 ## Docker Development Environment

@@ -203,4 +203,6 @@ The [Provisioner](/docs/W3DS%20Basics/Links) hosts `/provision`; the [Registry](
 - Understand [Authentication](/docs/W3DS%20Protocol/Authentication) - How users authenticate with platforms
 - Learn about [Signing](/docs/W3DS%20Protocol/Signing) - Signature creation and verification
 - Explore [Signature Formats](/docs/W3DS%20Protocol/Signature-Formats) - Technical details on cryptographic signatures
+- Read the [Data Ownership Rules](/docs/W3DS%20Basics/Data-Ownership-Rules) - Where data lives, and why the eVault is the source of truth
 - Build a platform with the [Post Platform Guide](/docs/Post%20Platform%20Guide/getting-started) - Step-by-step guide to creating a W3DS-compatible platform
+- Building with an AI coding agent? Load the [W3DS agent skill](/docs/Post%20Platform%20Guide/ai-agent-skill) first - it keeps the agent grounded in these docs instead of guessing
@@ -24,13 +24,16 @@ Returns a list of all available schemas.
 
 ```json
 [
- { "id": "550e8400-e29b-41d4-a716-446655440000", "title": "User" },
- { "id": "550e8400-e29b-41d4-a716-446655440001", "title": "SocialMediaPost" }
+ { "id": "550e8400-e29b-41d4-a716-446655440000", "title": "User", "domain": "identity" },
+ { "id": "550e8400-e29b-41d4-a716-446655440001", "title": "SocialMediaPost", "domain": "social" }
 ]
 ```
 
 - `id`: Schema W3ID (`schemaId`).
 - `title`: Human-readable schema title.
+- `domain`: The domain the schema belongs to, or `null` if untagged. See [GET /domains](#get-domains).
+
+This endpoint is the only correct way to obtain a `schemaId`. Match on `title`, then confirm the field names with `GET /schemas/:id` before writing a mapping. Schema IDs are not derivable, not sequential, and not stable enough to recall from memory — a wrong `schemaId` means every awareness packet for that type is silently dropped by receiving platforms.
 
 ### GET /schemas/:id
 
@@ -44,6 +47,30 @@ Returns the full JSON Schema for the given W3ID. Use this when you need the comp
 
 - **404**: Schema not found for the given W3ID.
 
+### GET /domains
+
+Returns the domain list every schema is tagged with — the same list a platform is granted access to, one domain at a time.
+
+**Response** (200):
+
+```json
+{
+ "schemaId": "<the Domain schema's own W3ID>",
+ "domains": [
+ { "id": "identity", "label": "Identity", "description": "..." },
+ { "id": "social", "label": "Social", "description": "..." }
+ ]
+}
+```
+
+The list is not a separate config file: it is read from the `Domain` schema's own enum, so it is versioned, browsable and fetchable like any other type.
+
+### GET /domains/:id/schemas
+
+Returns every schema under one domain: `{ "domain": { ... }, "schemas": [ { "id", "title" } ] }`. **404** if the domain does not exist.
+
+Use this when you know the subject area but not the type name — "what does W3DS already have for finance?" — before concluding that nothing fits and [proposing a new ontology](#proposing-a-new-ontology).
+
 ### Human-facing viewer
 
 - **GET /** — Renders a viewer page that lists schemas and supports search. Optional query `?q=...` filters by title or ID; `?schema=<id>` shows one schema.
@@ -83,6 +110,68 @@ Example (conceptually):
 
 In eVault, a MetaEnvelope for a post would have `ontology: "550e8400-e29b-41d4-a716-446655440001"`, and its Envelopes would have `ontology` values such as `content`, `authorId`, `createdAt`.
 
+## Proposing a new ontology
+
+Nothing in W3DS obliges you to squeeze your data into an existing type. If no schema fits what you are modelling, the correct move is to **propose a new one** — never to invent a `schemaId` and ship it.
+
+An invented `schemaId` does not fail loudly. The MetaEnvelope is written, the awareness packet fans out, and every receiving platform finds no mapping for that schema and drops it. The data becomes unreachable to the ecosystem while looking perfectly healthy on the platform that wrote it.
+
+### Before proposing
+
+1. `GET /schemas` and search the titles.
+2. `GET /domains/:id/schemas` for the domain your data belongs to.
+3. Read the near misses in full with `GET /schemas/:id`.
+
+Reuse beats addition, and **extending a near match by PR beats creating a parallel type**. Two schemas that mean the same thing split the ecosystem in half: platforms mapping one will not see data from platforms mapping the other.
+
+### Write the schema
+
+Schemas are ordinary files in the [prototype repository](https://github.com/MetaState-Prototype-Project/prototype), under `services/ontology/schemas/<name>.json`. The service loads the directory into an in-memory index at boot; there is no database and no registration call.
+
+```json
+{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "schemaId": "<a freshly generated random UUIDv4>",
+ "title": "Bookmark",
+ "domain": "productivity",
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "format": "uuid",
+ "description": "The unique identifier for the bookmark"
+ },
+ "userId": {
+ "type": "string",
+ "format": "uuid",
+ "description": "The ID of the user who created the bookmark"
+ },
+ "createdAt": {
+ "type": "string",
+ "format": "date-time",
+ "description": "When the bookmark was created"
+ }
+ },
+ "required": ["id", "userId", "createdAt"],
+ "additionalProperties": false
+}
+```
+
+Requirements:
+
+- **`schemaId`** — a freshly generated random UUIDv4 (`uuidgen`, `crypto.randomUUID()`). Never derive one from an existing ID, never continue a numeric sequence you notice in the directory, and never reuse an ID from another schema.
+- **`title`** — the type name as other platforms will search for it. Singular, PascalCase.
+- **`domain`** — one value from the `Domain` schema's enum, fetchable at `GET /domains`. Platforms are granted access domain by domain, so this decides who can consume the type.
+- **`properties`** — every field with a `description`. Each property name becomes an Envelope's `ontology` value in the eVault, so **name fields for their cross-platform meaning, not after your local columns**. `authorId` is a W3DS field name; `fk_user_id_2` is not.
+- **`required`** — the fields a consumer can rely on being present.
+- **`additionalProperties`** — `false`, unless you have a specific reason.
+
+### Open the PR
+
+Add the file, open a pull request against the prototype repository, and say in the description what the type is for and which platform will write it. Reviewers will ask whether an existing schema could have carried the data — answer that question in the PR body and you will save a round trip.
+
+Until the PR merges and the service redeploys, **the type does not exist**. Do not ship a `mapping.json` referencing an unmerged `schemaId`; the sync will look fine locally and silently drop everywhere else.
+
 ## Available schemas
 
 To see all available schemas, call `GET /schemas` on the [Ontology production service](/docs/W3DS%20Basics/Links) or browse the [viewer](https://ontology.w3ds.metastate.foundation/) at the production base URL.
@@ -97,3 +186,4 @@ To see all available schemas, call `GET /schemas` on the [Ontology production se
 - [eVault](/docs/Infrastructure/eVault) — MetaEnvelopes, Envelopes, and the `ontology` field
 - [W3DS Basics](/docs/W3DS%20Basics/getting-started) — Ontology and schema concepts
 - [Links](/docs/W3DS%20Basics/Links) — Production Ontology base URL
+- [Data Ownership Rules](/docs/W3DS%20Basics/Data-Ownership-Rules) — why every persisted entity needs an ontology
@@ -2,6 +2,8 @@
 
 **[Documentation](https://docs.w3ds.metastate.foundation)** — Getting started with W3DS and the MetaState prototype.
 
+**Building with an AI coding agent?** Load the [W3DS agent skill](https://docs.w3ds.metastate.foundation/docs/Post%20Platform%20Guide/ai-agent-skill) — `npx skills add MetaState-Prototype-Project/prototype@w3ds`, or point a fetch-capable agent at [`/skill/SKILL.md`](https://docs.w3ds.metastate.foundation/skill/SKILL.md) and [`/llms.txt`](https://docs.w3ds.metastate.foundation/llms.txt).
+
 **Quick start (registry + evault-core + dev-sandbox):** see **[QUICKSTART.md](QUICKSTART.md)** — one script to run Postgres + Neo4j in Docker and the core services locally. Dev sandbox runs at **http://localhost:8080**.
 
 ## Docker Development Environment

@@ -203,4 +203,6 @@ The [Provisioner](/docs/W3DS%20Basics/Links) hosts `/provision`; the [Registry](
 - Understand [Authentication](/docs/W3DS%20Protocol/Authentication) - How users authenticate with platforms
 - Learn about [Signing](/docs/W3DS%20Protocol/Signing) - Signature creation and verification
 - Explore [Signature Formats](/docs/W3DS%20Protocol/Signature-Formats) - Technical details on cryptographic signatures
+- Read the [Data Ownership Rules](/docs/W3DS%20Basics/Data-Ownership-Rules) - Where data lives, and why the eVault is the source of truth
 - Build a platform with the [Post Platform Guide](/docs/Post%20Platform%20Guide/getting-started) - Step-by-step guide to creating a W3DS-compatible platform
+- Building with an AI coding agent? Load the [W3DS agent skill](/docs/Post%20Platform%20Guide/ai-agent-skill) first - it keeps the agent grounded in these docs instead of guessing
@@ -24,13 +24,16 @@ Returns a list of all available schemas.
 
 ```json
 [
- { "id": "550e8400-e29b-41d4-a716-446655440000", "title": "User" },
- { "id": "550e8400-e29b-41d4-a716-446655440001", "title": "SocialMediaPost" }
+ { "id": "550e8400-e29b-41d4-a716-446655440000", "title": "User", "domain": "identity" },
+ { "id": "550e8400-e29b-41d4-a716-446655440001", "title": "SocialMediaPost", "domain": "social" }
 ]
 ```
 
 - `id`: Schema W3ID (`schemaId`).
 - `title`: Human-readable schema title.
+- `domain`: The domain the schema belongs to, or `null` if untagged. See [GET /domains](#get-domains).
+
+This endpoint is the only correct way to obtain a `schemaId`. Match on `title`, then confirm the field names with `GET /schemas/:id` before writing a mapping. Schema IDs are not derivable, not sequential, and not stable enough to recall from memory — a wrong `schemaId` means every awareness packet for that type is silently dropped by receiving platforms.
 
 ### GET /schemas/:id
 
@@ -44,6 +47,30 @@ Returns the full JSON Schema for the given W3ID. Use this when you need the comp
 
 - **404**: Schema not found for the given W3ID.
 
+### GET /domains
+
+Returns the domain list every schema is tagged with — the same list a platform is granted access to, one domain at a time.
+
+**Response** (200):
+
+```json
+{
+ "schemaId": "<the Domain schema's own W3ID>",
+ "domains": [
+ { "id": "identity", "label": "Identity", "description": "..." },
+ { "id": "social", "label": "Social", "description": "..." }
+ ]
+}
+```
+
+The list is not a separate config file: it is read from the `Domain` schema's own enum, so it is versioned, browsable and fetchable like any other type.
+
+### GET /domains/:id/schemas
+
+Returns every schema under one domain: `{ "domain": { ... }, "schemas": [ { "id", "title" } ] }`. **404** if the domain does not exist.
+
+Use this when you know the subject area but not the type name — "what does W3DS already have for finance?" — before concluding that nothing fits and [proposing a new ontology](#proposing-a-new-ontology).
+
 ### Human-facing viewer
 
 - **GET /** — Renders a viewer page that lists schemas and supports search. Optional query `?q=...` filters by title or ID; `?schema=<id>` shows one schema.
@@ -83,6 +110,68 @@ Example (conceptually):
 
 In eVault, a MetaEnvelope for a post would have `ontology: "550e8400-e29b-41d4-a716-446655440001"`, and its Envelopes would have `ontology` values such as `content`, `authorId`, `createdAt`.
 
+## Proposing a new ontology
+
+Nothing in W3DS obliges you to squeeze your data into an existing type. If no schema fits what you are modelling, the correct move is to **propose a new one** — never to invent a `schemaId` and ship it.
+
+An invented `schemaId` does not fail loudly. The MetaEnvelope is written, the awareness packet fans out, and every receiving platform finds no mapping for that schema and drops it. The data becomes unreachable to the ecosystem while looking perfectly healthy on the platform that wrote it.
+
+### Before proposing
+
+1. `GET /schemas` and search the titles.
+2. `GET /domains/:id/schemas` for the domain your data belongs to.
+3. Read the near misses in full with `GET /schemas/:id`.
+
+Reuse beats addition, and **extending a near match by PR beats creating a parallel type**. Two schemas that mean the same thing split the ecosystem in half: platforms mapping one will not see data from platforms mapping the other.
+
+### Write the schema
+
+Schemas are ordinary files in the [prototype repository](https://github.com/MetaState-Prototype-Project/prototype), under `services/ontology/schemas/<name>.json`. The service loads the directory into an in-memory index at boot; there is no database and no registration call.
+
+```json
+{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "schemaId": "<a freshly generated random UUIDv4>",
+ "title": "Bookmark",
+ "domain": "productivity",
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "format": "uuid",
+ "description": "The unique identifier for the bookmark"
+ },
+ "userId": {
+ "type": "string",
+ "format": "uuid",
+ "description": "The ID of the user who created the bookmark"
+ },
+ "createdAt": {
+ "type": "string",
+ "format": "date-time",
+ "description": "When the bookmark was created"
+ }
+ },
+ "required": ["id", "userId", "createdAt"],
+ "additionalProperties": false
+}
+```
+
+Requirements:
+
+- **`schemaId`** — a freshly generated random UUIDv4 (`uuidgen`, `crypto.randomUUID()`). Never derive one from an existing ID, never continue a numeric sequence you notice in the directory, and never reuse an ID from another schema.
+- **`title`** — the type name as other platforms will search for it. Singular, PascalCase.
+- **`domain`** — one value from the `Domain` schema's enum, fetchable at `GET /domains`. Platforms are granted access domain by domain, so this decides who can consume the type.
+- **`properties`** — every field with a `description`. Each property name becomes an Envelope's `ontology` value in the eVault, so **name fields for their cross-platform meaning, not after your local columns**. `authorId` is a W3DS field name; `fk_user_id_2` is not.
+- **`required`** — the fields a consumer can rely on being present.
+- **`additionalProperties`** — `false`, unless you have a specific reason.
+
+### Open the PR
+
+Add the file, open a pull request against the prototype repository, and say in the description what the type is for and which platform will write it. Reviewers will ask whether an existing schema could have carried the data — answer that question in the PR body and you will save a round trip.
+
+Until the PR merges and the service redeploys, **the type does not exist**. Do not ship a `mapping.json` referencing an unmerged `schemaId`; the sync will look fine locally and silently drop everywhere else.
+
 ## Available schemas
 
 To see all available schemas, call `GET /schemas` on the [Ontology production service](/docs/W3DS%20Basics/Links) or browse the [viewer](https://ontology.w3ds.metastate.foundation/) at the production base URL.
@@ -97,3 +186,4 @@ To see all available schemas, call `GET /schemas` on the [Ontology production se
 - [eVault](/docs/Infrastructure/eVault) — MetaEnvelopes, Envelopes, and the `ontology` field
 - [W3DS Basics](/docs/W3DS%20Basics/getting-started) — Ontology and schema concepts
 - [Links](/docs/W3DS%20Basics/Links) — Production Ontology base URL
+- [Data Ownership Rules](/docs/W3DS%20Basics/Data-Ownership-Rules) — why every persisted entity needs an ontology
@@ -2,6 +2,8 @@
 
 **[Documentation](https://docs.w3ds.metastate.foundation)** — Getting started with W3DS and the MetaState prototype.
 
+**Building with an AI coding agent?** Load the [W3DS agent skill](https://docs.w3ds.metastate.foundation/docs/Post%20Platform%20Guide/ai-agent-skill) — `npx skills add MetaState-Prototype-Project/prototype@w3ds`, or point a fetch-capable agent at [`/skill/SKILL.md`](https://docs.w3ds.metastate.foundation/skill/SKILL.md) and [`/llms.txt`](https://docs.w3ds.metastate.foundation/llms.txt).
+
 **Quick start (registry + evault-core + dev-sandbox):** see **[QUICKSTART.md](QUICKSTART.md)** — one script to run Postgres + Neo4j in Docker and the core services locally. Dev sandbox runs at **http://localhost:8080**.
 
 ## Docker Development Environment

@@ -203,4 +203,6 @@ The [Provisioner](/docs/W3DS%20Basics/Links) hosts `/provision`; the [Registry](
 - Understand [Authentication](/docs/W3DS%20Protocol/Authentication) - How users authenticate with platforms
 - Learn about [Signing](/docs/W3DS%20Protocol/Signing) - Signature creation and verification
 - Explore [Signature Formats](/docs/W3DS%20Protocol/Signature-Formats) - Technical details on cryptographic signatures
+- Read the [Data Ownership Rules](/docs/W3DS%20Basics/Data-Ownership-Rules) - Where data lives, and why the eVault is the source of truth
 - Build a platform with the [Post Platform Guide](/docs/Post%20Platform%20Guide/getting-started) - Step-by-step guide to creating a W3DS-compatible platform
+- Building with an AI coding agent? Load the [W3DS agent skill](/docs/Post%20Platform%20Guide/ai-agent-skill) first - it keeps the agent grounded in these docs instead of guessing
@@ -24,13 +24,16 @@ Returns a list of all available schemas.
 
 ```json
 [
- { "id": "550e8400-e29b-41d4-a716-446655440000", "title": "User" },
- { "id": "550e8400-e29b-41d4-a716-446655440001", "title": "SocialMediaPost" }
+ { "id": "550e8400-e29b-41d4-a716-446655440000", "title": "User", "domain": "identity" },
+ { "id": "550e8400-e29b-41d4-a716-446655440001", "title": "SocialMediaPost", "domain": "social" }
 ]
 ```
 
 - `id`: Schema W3ID (`schemaId`).
 - `title`: Human-readable schema title.
+- `domain`: The domain the schema belongs to, or `null` if untagged. See [GET /domains](#get-domains).
+
+This endpoint is the only correct way to obtain a `schemaId`. Match on `title`, then confirm the field names with `GET /schemas/:id` before writing a mapping. Schema IDs are not derivable, not sequential, and not stable enough to recall from memory — a wrong `schemaId` means every awareness packet for that type is silently dropped by receiving platforms.
 
 ### GET /schemas/:id
 
@@ -44,6 +47,30 @@ Returns the full JSON Schema for the given W3ID. Use this when you need the comp
 
 - **404**: Schema not found for the given W3ID.
 
+### GET /domains
+
+Returns the domain list every schema is tagged with — the same list a platform is granted access to, one domain at a time.
+
+**Response** (200):
+
+```json
+{
+ "schemaId": "<the Domain schema's own W3ID>",
+ "domains": [
+ { "id": "identity", "label": "Identity", "description": "..." },
+ { "id": "social", "label": "Social", "description": "..." }
+ ]
+}
+```
+
+The list is not a separate config file: it is read from the `Domain` schema's own enum, so it is versioned, browsable and fetchable like any other type.
+
+### GET /domains/:id/schemas
+
+Returns every schema under one domain: `{ "domain": { ... }, "schemas": [ { "id", "title" } ] }`. **404** if the domain does not exist.
+
+Use this when you know the subject area but not the type name — "what does W3DS already have for finance?" — before concluding that nothing fits and [proposing a new ontology](#proposing-a-new-ontology).
+
 ### Human-facing viewer
 
 - **GET /** — Renders a viewer page that lists schemas and supports search. Optional query `?q=...` filters by title or ID; `?schema=<id>` shows one schema.
@@ -83,6 +110,68 @@ Example (conceptually):
 
 In eVault, a MetaEnvelope for a post would have `ontology: "550e8400-e29b-41d4-a716-446655440001"`, and its Envelopes would have `ontology` values such as `content`, `authorId`, `createdAt`.
 
+## Proposing a new ontology
+
+Nothing in W3DS obliges you to squeeze your data into an existing type. If no schema fits what you are modelling, the correct move is to **propose a new one** — never to invent a `schemaId` and ship it.
+
+An invented `schemaId` does not fail loudly. The MetaEnvelope is written, the awareness packet fans out, and every receiving platform finds no mapping for that schema and drops it. The data becomes unreachable to the ecosystem while looking perfectly healthy on the platform that wrote it.
+
+### Before proposing
+
+1. `GET /schemas` and search the titles.
+2. `GET /domains/:id/schemas` for the domain your data belongs to.
+3. Read the near misses in full with `GET /schemas/:id`.
+
+Reuse beats addition, and **extending a near match by PR beats creating a parallel type**. Two schemas that mean the same thing split the ecosystem in half: platforms mapping one will not see data from platforms mapping the other.
+
+### Write the schema
+
+Schemas are ordinary files in the [prototype repository](https://github.com/MetaState-Prototype-Project/prototype), under `services/ontology/schemas/<name>.json`. The service loads the directory into an in-memory index at boot; there is no database and no registration call.
+
+```json
+{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "schemaId": "<a freshly generated random UUIDv4>",
+ "title": "Bookmark",
+ "domain": "productivity",
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "format": "uuid",
+ "description": "The unique identifier for the bookmark"
+ },
+ "userId": {
+ "type": "string",
+ "format": "uuid",
+ "description": "The ID of the user who created the bookmark"
+ },
+ "createdAt": {
+ "type": "string",
+ "format": "date-time",
+ "description": "When the bookmark was created"
+ }
+ },
+ "required": ["id", "userId", "createdAt"],
+ "additionalProperties": false
+}
+```
+
+Requirements:
+
+- **`schemaId`** — a freshly generated random UUIDv4 (`uuidgen`, `crypto.randomUUID()`). Never derive one from an existing ID, never continue a numeric sequence you notice in the directory, and never reuse an ID from another schema.
+- **`title`** — the type name as other platforms will search for it. Singular, PascalCase.
+- **`domain`** — one value from the `Domain` schema's enum, fetchable at `GET /domains`. Platforms are granted access domain by domain, so this decides who can consume the type.
+- **`properties`** — every field with a `description`. Each property name becomes an Envelope's `ontology` value in the eVault, so **name fields for their cross-platform meaning, not after your local columns**. `authorId` is a W3DS field name; `fk_user_id_2` is not.
+- **`required`** — the fields a consumer can rely on being present.
+- **`additionalProperties`** — `false`, unless you have a specific reason.
+
+### Open the PR
+
+Add the file, open a pull request against the prototype repository, and say in the description what the type is for and which platform will write it. Reviewers will ask whether an existing schema could have carried the data — answer that question in the PR body and you will save a round trip.
+
+Until the PR merges and the service redeploys, **the type does not exist**. Do not ship a `mapping.json` referencing an unmerged `schemaId`; the sync will look fine locally and silently drop everywhere else.
+
 ## Available schemas
 
 To see all available schemas, call `GET /schemas` on the [Ontology production service](/docs/W3DS%20Basics/Links) or browse the [viewer](https://ontology.w3ds.metastate.foundation/) at the production base URL.
@@ -97,3 +186,4 @@ To see all available schemas, call `GET /schemas` on the [Ontology production se
 - [eVault](/docs/Infrastructure/eVault) — MetaEnvelopes, Envelopes, and the `ontology` field
 - [W3DS Basics](/docs/W3DS%20Basics/getting-started) — Ontology and schema concepts
 - [Links](/docs/W3DS%20Basics/Links) — Production Ontology base URL
+- [Data Ownership Rules](/docs/W3DS%20Basics/Data-Ownership-Rules) — why every persisted entity needs an ontology
@@ -2,6 +2,8 @@
 
 **[Documentation](https://docs.w3ds.metastate.foundation)** — Getting started with W3DS and the MetaState prototype.
 
+**Building with an AI coding agent?** Load the [W3DS agent skill](https://docs.w3ds.metastate.foundation/docs/Post%20Platform%20Guide/ai-agent-skill) — `npx skills add MetaState-Prototype-Project/prototype@w3ds`, or point a fetch-capable agent at [`/skill/SKILL.md`](https://docs.w3ds.metastate.foundation/skill/SKILL.md) and [`/llms.txt`](https://docs.w3ds.metastate.foundation/llms.txt).
+
 **Quick start (registry + evault-core + dev-sandbox):** see **[QUICKSTART.md](QUICKSTART.md)** — one script to run Postgres + Neo4j in Docker and the core services locally. Dev sandbox runs at **http://localhost:8080**.
 
 ## Docker Development Environment

@@ -203,4 +203,6 @@ The [Provisioner](/docs/W3DS%20Basics/Links) hosts `/provision`; the [Registry](
 - Understand [Authentication](/docs/W3DS%20Protocol/Authentication) - How users authenticate with platforms
 - Learn about [Signing](/docs/W3DS%20Protocol/Signing) - Signature creation and verification
 - Explore [Signature Formats](/docs/W3DS%20Protocol/Signature-Formats) - Technical details on cryptographic signatures
+- Read the [Data Ownership Rules](/docs/W3DS%20Basics/Data-Ownership-Rules) - Where data lives, and why the eVault is the source of truth
 - Build a platform with the [Post Platform Guide](/docs/Post%20Platform%20Guide/getting-started) - Step-by-step guide to creating a W3DS-compatible platform
+- Building with an AI coding agent? Load the [W3DS agent skill](/docs/Post%20Platform%20Guide/ai-agent-skill) first - it keeps the agent grounded in these docs instead of guessing
@@ -24,13 +24,16 @@ Returns a list of all available schemas.
 
 ```json
 [
- { "id": "550e8400-e29b-41d4-a716-446655440000", "title": "User" },
- { "id": "550e8400-e29b-41d4-a716-446655440001", "title": "SocialMediaPost" }
+ { "id": "550e8400-e29b-41d4-a716-446655440000", "title": "User", "domain": "identity" },
+ { "id": "550e8400-e29b-41d4-a716-446655440001", "title": "SocialMediaPost", "domain": "social" }
 ]
 ```
 
 - `id`: Schema W3ID (`schemaId`).
 - `title`: Human-readable schema title.
+- `domain`: The domain the schema belongs to, or `null` if untagged. See [GET /domains](#get-domains).
+
+This endpoint is the only correct way to obtain a `schemaId`. Match on `title`, then confirm the field names with `GET /schemas/:id` before writing a mapping. Schema IDs are not derivable, not sequential, and not stable enough to recall from memory — a wrong `schemaId` means every awareness packet for that type is silently dropped by receiving platforms.
 
 ### GET /schemas/:id
 
@@ -44,6 +47,30 @@ Returns the full JSON Schema for the given W3ID. Use this when you need the comp
 
 - **404**: Schema not found for the given W3ID.
 
+### GET /domains
+
+Returns the domain list every schema is tagged with — the same list a platform is granted access to, one domain at a time.
+
+**Response** (200):
+
+```json
+{
+ "schemaId": "<the Domain schema's own W3ID>",
+ "domains": [
+ { "id": "identity", "label": "Identity", "description": "..." },
+ { "id": "social", "label": "Social", "description": "..." }
+ ]
+}
+```
+
+The list is not a separate config file: it is read from the `Domain` schema's own enum, so it is versioned, browsable and fetchable like any other type.
+
+### GET /domains/:id/schemas
+
+Returns every schema under one domain: `{ "domain": { ... }, "schemas": [ { "id", "title" } ] }`. **404** if the domain does not exist.
+
+Use this when you know the subject area but not the type name — "what does W3DS already have for finance?" — before concluding that nothing fits and [proposing a new ontology](#proposing-a-new-ontology).
+
 ### Human-facing viewer
 
 - **GET /** — Renders a viewer page that lists schemas and supports search. Optional query `?q=...` filters by title or ID; `?schema=<id>` shows one schema.
@@ -83,6 +110,68 @@ Example (conceptually):
 
 In eVault, a MetaEnvelope for a post would have `ontology: "550e8400-e29b-41d4-a716-446655440001"`, and its Envelopes would have `ontology` values such as `content`, `authorId`, `createdAt`.
 
+## Proposing a new ontology
+
+Nothing in W3DS obliges you to squeeze your data into an existing type. If no schema fits what you are modelling, the correct move is to **propose a new one** — never to invent a `schemaId` and ship it.
+
+An invented `schemaId` does not fail loudly. The MetaEnvelope is written, the awareness packet fans out, and every receiving platform finds no mapping for that schema and drops it. The data becomes unreachable to the ecosystem while looking perfectly healthy on the platform that wrote it.
+
+### Before proposing
+
+1. `GET /schemas` and search the titles.
+2. `GET /domains/:id/schemas` for the domain your data belongs to.
+3. Read the near misses in full with `GET /schemas/:id`.
+
+Reuse beats addition, and **extending a near match by PR beats creating a parallel type**. Two schemas that mean the same thing split the ecosystem in half: platforms mapping one will not see data from platforms mapping the other.
+
+### Write the schema
+
+Schemas are ordinary files in the [prototype repository](https://github.com/MetaState-Prototype-Project/prototype), under `services/ontology/schemas/<name>.json`. The service loads the directory into an in-memory index at boot; there is no database and no registration call.
+
+```json
+{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "schemaId": "<a freshly generated random UUIDv4>",
+ "title": "Bookmark",
+ "domain": "productivity",
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "format": "uuid",
+ "description": "The unique identifier for the bookmark"
+ },
+ "userId": {
+ "type": "string",
+ "format": "uuid",
+ "description": "The ID of the user who created the bookmark"
+ },
+ "createdAt": {
+ "type": "string",
+ "format": "date-time",
+ "description": "When the bookmark was created"
+ }
+ },
+ "required": ["id", "userId", "createdAt"],
+ "additionalProperties": false
+}
+```
+
+Requirements:
+
+- **`schemaId`** — a freshly generated random UUIDv4 (`uuidgen`, `crypto.randomUUID()`). Never derive one from an existing ID, never continue a numeric sequence you notice in the directory, and never reuse an ID from another schema.
+- **`title`** — the type name as other platforms will search for it. Singular, PascalCase.
+- **`domain`** — one value from the `Domain` schema's enum, fetchable at `GET /domains`. Platforms are granted access domain by domain, so this decides who can consume the type.
+- **`properties`** — every field with a `description`. Each property name becomes an Envelope's `ontology` value in the eVault, so **name fields for their cross-platform meaning, not after your local columns**. `authorId` is a W3DS field name; `fk_user_id_2` is not.
+- **`required`** — the fields a consumer can rely on being present.
+- **`additionalProperties`** — `false`, unless you have a specific reason.
+
+### Open the PR
+
+Add the file, open a pull request against the prototype repository, and say in the description what the type is for and which platform will write it. Reviewers will ask whether an existing schema could have carried the data — answer that question in the PR body and you will save a round trip.
+
+Until the PR merges and the service redeploys, **the type does not exist**. Do not ship a `mapping.json` referencing an unmerged `schemaId`; the sync will look fine locally and silently drop everywhere else.
+
 ## Available schemas
 
 To see all available schemas, call `GET /schemas` on the [Ontology production service](/docs/W3DS%20Basics/Links) or browse the [viewer](https://ontology.w3ds.metastate.foundation/) at the production base URL.
@@ -97,3 +186,4 @@ To see all available schemas, call `GET /schemas` on the [Ontology production se
 - [eVault](/docs/Infrastructure/eVault) — MetaEnvelopes, Envelopes, and the `ontology` field
 - [W3DS Basics](/docs/W3DS%20Basics/getting-started) — Ontology and schema concepts
 - [Links](/docs/W3DS%20Basics/Links) — Production Ontology base URL
+- [Data Ownership Rules](/docs/W3DS%20Basics/Data-Ownership-Rules) — why every persisted entity needs an ontology
@@ -2,6 +2,8 @@
 
 **[Documentation](https://docs.w3ds.metastate.foundation)** — Getting started with W3DS and the MetaState prototype.
 
+**Building with an AI coding agent?** Load the [W3DS agent skill](https://docs.w3ds.metastate.foundation/docs/Post%20Platform%20Guide/ai-agent-skill) — `npx skills add MetaState-Prototype-Project/prototype@w3ds`, or point a fetch-capable agent at [`/skill/SKILL.md`](https://docs.w3ds.metastate.foundation/skill/SKILL.md) and [`/llms.txt`](https://docs.w3ds.metastate.foundation/llms.txt).
+
 **Quick start (registry + evault-core + dev-sandbox):** see **[QUICKSTART.md](QUICKSTART.md)** — one script to run Postgres + Neo4j in Docker and the core services locally. Dev sandbox runs at **http://localhost:8080**.
 
 ## Docker Development Environment

@@ -203,4 +203,6 @@ The [Provisioner](/docs/W3DS%20Basics/Links) hosts `/provision`; the [Registry](
 - Understand [Authentication](/docs/W3DS%20Protocol/Authentication) - How users authenticate with platforms
 - Learn about [Signing](/docs/W3DS%20Protocol/Signing) - Signature creation and verification
 - Explore [Signature Formats](/docs/W3DS%20Protocol/Signature-Formats) - Technical details on cryptographic signatures
+- Read the [Data Ownership Rules](/docs/W3DS%20Basics/Data-Ownership-Rules) - Where data lives, and why the eVault is the source of truth
 - Build a platform with the [Post Platform Guide](/docs/Post%20Platform%20Guide/getting-started) - Step-by-step guide to creating a W3DS-compatible platform
+- Building with an AI coding agent? Load the [W3DS agent skill](/docs/Post%20Platform%20Guide/ai-agent-skill) first - it keeps the agent grounded in these docs instead of guessing
@@ -24,13 +24,16 @@ Returns a list of all available schemas.
 
 ```json
 [
- { "id": "550e8400-e29b-41d4-a716-446655440000", "title": "User" },
- { "id": "550e8400-e29b-41d4-a716-446655440001", "title": "SocialMediaPost" }
+ { "id": "550e8400-e29b-41d4-a716-446655440000", "title": "User", "domain": "identity" },
+ { "id": "550e8400-e29b-41d4-a716-446655440001", "title": "SocialMediaPost", "domain": "social" }
 ]
 ```
 
 - `id`: Schema W3ID (`schemaId`).
 - `title`: Human-readable schema title.
+- `domain`: The domain the schema belongs to, or `null` if untagged. See [GET /domains](#get-domains).
+
+This endpoint is the only correct way to obtain a `schemaId`. Match on `title`, then confirm the field names with `GET /schemas/:id` before writing a mapping. Schema IDs are not derivable, not sequential, and not stable enough to recall from memory — a wrong `schemaId` means every awareness packet for that type is silently dropped by receiving platforms.
 
 ### GET /schemas/:id
 
@@ -44,6 +47,30 @@ Returns the full JSON Schema for the given W3ID. Use this when you need the comp
 
 - **404**: Schema not found for the given W3ID.
 
+### GET /domains
+
+Returns the domain list every schema is tagged with — the same list a platform is granted access to, one domain at a time.
+
+**Response** (200):
+
+```json
+{
+ "schemaId": "<the Domain schema's own W3ID>",
+ "domains": [
+ { "id": "identity", "label": "Identity", "description": "..." },
+ { "id": "social", "label": "Social", "description": "..." }
+ ]
+}
+```
+
+The list is not a separate config file: it is read from the `Domain` schema's own enum, so it is versioned, browsable and fetchable like any other type.
+
+### GET /domains/:id/schemas
+
+Returns every schema under one domain: `{ "domain": { ... }, "schemas": [ { "id", "title" } ] }`. **404** if the domain does not exist.
+
+Use this when you know the subject area but not the type name — "what does W3DS already have for finance?" — before concluding that nothing fits and [proposing a new ontology](#proposing-a-new-ontology).
+
 ### Human-facing viewer
 
 - **GET /** — Renders a viewer page that lists schemas and supports search. Optional query `?q=...` filters by title or ID; `?schema=<id>` shows one schema.
@@ -83,6 +110,68 @@ Example (conceptually):
 
 In eVault, a MetaEnvelope for a post would have `ontology: "550e8400-e29b-41d4-a716-446655440001"`, and its Envelopes would have `ontology` values such as `content`, `authorId`, `createdAt`.
 
+## Proposing a new ontology
+
+Nothing in W3DS obliges you to squeeze your data into an existing type. If no schema fits what you are modelling, the correct move is to **propose a new one** — never to invent a `schemaId` and ship it.
+
+An invented `schemaId` does not fail loudly. The MetaEnvelope is written, the awareness packet fans out, and every receiving platform finds no mapping for that schema and drops it. The data becomes unreachable to the ecosystem while looking perfectly healthy on the platform that wrote it.
+
+### Before proposing
+
+1. `GET /schemas` and search the titles.
+2. `GET /domains/:id/schemas` for the domain your data belongs to.
+3. Read the near misses in full with `GET /schemas/:id`.
+
+Reuse beats addition, and **extending a near match by PR beats creating a parallel type**. Two schemas that mean the same thing split the ecosystem in half: platforms mapping one will not see data from platforms mapping the other.
+
+### Write the schema
+
+Schemas are ordinary files in the [prototype repository](https://github.com/MetaState-Prototype-Project/prototype), under `services/ontology/schemas/<name>.json`. The service loads the directory into an in-memory index at boot; there is no database and no registration call.
+
+```json
+{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "schemaId": "<a freshly generated random UUIDv4>",
+ "title": "Bookmark",
+ "domain": "productivity",
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "format": "uuid",
+ "description": "The unique identifier for the bookmark"
+ },
+ "userId": {
+ "type": "string",
+ "format": "uuid",
+ "description": "The ID of the user who created the bookmark"
+ },
+ "createdAt": {
+ "type": "string",
+ "format": "date-time",
+ "description": "When the bookmark was created"
+ }
+ },
+ "required": ["id", "userId", "createdAt"],
+ "additionalProperties": false
+}
+```
+
+Requirements:
+
+- **`schemaId`** — a freshly generated random UUIDv4 (`uuidgen`, `crypto.randomUUID()`). Never derive one from an existing ID, never continue a numeric sequence you notice in the directory, and never reuse an ID from another schema.
+- **`title`** — the type name as other platforms will search for it. Singular, PascalCase.
+- **`domain`** — one value from the `Domain` schema's enum, fetchable at `GET /domains`. Platforms are granted access domain by domain, so this decides who can consume the type.
+- **`properties`** — every field with a `description`. Each property name becomes an Envelope's `ontology` value in the eVault, so **name fields for their cross-platform meaning, not after your local columns**. `authorId` is a W3DS field name; `fk_user_id_2` is not.
+- **`required`** — the fields a consumer can rely on being present.
+- **`additionalProperties`** — `false`, unless you have a specific reason.
+
+### Open the PR
+
+Add the file, open a pull request against the prototype repository, and say in the description what the type is for and which platform will write it. Reviewers will ask whether an existing schema could have carried the data — answer that question in the PR body and you will save a round trip.
+
+Until the PR merges and the service redeploys, **the type does not exist**. Do not ship a `mapping.json` referencing an unmerged `schemaId`; the sync will look fine locally and silently drop everywhere else.
+
 ## Available schemas
 
 To see all available schemas, call `GET /schemas` on the [Ontology production service](/docs/W3DS%20Basics/Links) or browse the [viewer](https://ontology.w3ds.metastate.foundation/) at the production base URL.
@@ -97,3 +186,4 @@ To see all available schemas, call `GET /schemas` on the [Ontology production se
 - [eVault](/docs/Infrastructure/eVault) — MetaEnvelopes, Envelopes, and the `ontology` field
 - [W3DS Basics](/docs/W3DS%20Basics/getting-started) — Ontology and schema concepts
 - [Links](/docs/W3DS%20Basics/Links) — Production Ontology base URL
+- [Data Ownership Rules](/docs/W3DS%20Basics/Data-Ownership-Rules) — why every persisted entity needs an ontology
@@ -2,6 +2,8 @@
 
 **[Documentation](https://docs.w3ds.metastate.foundation)** — Getting started with W3DS and the MetaState prototype.
 
+**Building with an AI coding agent?** Load the [W3DS agent skill](https://docs.w3ds.metastate.foundation/docs/Post%20Platform%20Guide/ai-agent-skill) — `npx skills add MetaState-Prototype-Project/prototype@w3ds`, or point a fetch-capable agent at [`/skill/SKILL.md`](https://docs.w3ds.metastate.foundation/skill/SKILL.md) and [`/llms.txt`](https://docs.w3ds.metastate.foundation/llms.txt).
+
 **Quick start (registry + evault-core + dev-sandbox):** see **[QUICKSTART.md](QUICKSTART.md)** — one script to run Postgres + Neo4j in Docker and the core services locally. Dev sandbox runs at **http://localhost:8080**.
 
 ## Docker Development Environment

@@ -203,4 +203,6 @@ The [Provisioner](/docs/W3DS%20Basics/Links) hosts `/provision`; the [Registry](
 - Understand [Authentication](/docs/W3DS%20Protocol/Authentication) - How users authenticate with platforms
 - Learn about [Signing](/docs/W3DS%20Protocol/Signing) - Signature creation and verification
 - Explore [Signature Formats](/docs/W3DS%20Protocol/Signature-Formats) - Technical details on cryptographic signatures
+- Read the [Data Ownership Rules](/docs/W3DS%20Basics/Data-Ownership-Rules) - Where data lives, and why the eVault is the source of truth
 - Build a platform with the [Post Platform Guide](/docs/Post%20Platform%20Guide/getting-started) - Step-by-step guide to creating a W3DS-compatible platform
+- Building with an AI coding agent? Load the [W3DS agent skill](/docs/Post%20Platform%20Guide/ai-agent-skill) first - it keeps the agent grounded in these docs instead of guessing
@@ -24,13 +24,16 @@ Returns a list of all available schemas.
 
 ```json
 [
- { "id": "550e8400-e29b-41d4-a716-446655440000", "title": "User" },
- { "id": "550e8400-e29b-41d4-a716-446655440001", "title": "SocialMediaPost" }
+ { "id": "550e8400-e29b-41d4-a716-446655440000", "title": "User", "domain": "identity" },
+ { "id": "550e8400-e29b-41d4-a716-446655440001", "title": "SocialMediaPost", "domain": "social" }
 ]
 ```
 
 - `id`: Schema W3ID (`schemaId`).
 - `title`: Human-readable schema title.
+- `domain`: The domain the schema belongs to, or `null` if untagged. See [GET /domains](#get-domains).
+
+This endpoint is the only correct way to obtain a `schemaId`. Match on `title`, then confirm the field names with `GET /schemas/:id` before writing a mapping. Schema IDs are not derivable, not sequential, and not stable enough to recall from memory — a wrong `schemaId` means every awareness packet for that type is silently dropped by receiving platforms.
 
 ### GET /schemas/:id
 
@@ -44,6 +47,30 @@ Returns the full JSON Schema for the given W3ID. Use this when you need the comp
 
 - **404**: Schema not found for the given W3ID.
 
+### GET /domains
+
+Returns the domain list every schema is tagged with — the same list a platform is granted access to, one domain at a time.
+
+**Response** (200):
+
+```json
+{
+ "schemaId": "<the Domain schema's own W3ID>",
+ "domains": [
+ { "id": "identity", "label": "Identity", "description": "..." },
+ { "id": "social", "label": "Social", "description": "..." }
+ ]
+}
+```
+
+The list is not a separate config file: it is read from the `Domain` schema's own enum, so it is versioned, browsable and fetchable like any other type.
+
+### GET /domains/:id/schemas
+
+Returns every schema under one domain: `{ "domain": { ... }, "schemas": [ { "id", "title" } ] }`. **404** if the domain does not exist.
+
+Use this when you know the subject area but not the type name — "what does W3DS already have for finance?" — before concluding that nothing fits and [proposing a new ontology](#proposing-a-new-ontology).
+
 ### Human-facing viewer
 
 - **GET /** — Renders a viewer page that lists schemas and supports search. Optional query `?q=...` filters by title or ID; `?schema=<id>` shows one schema.
@@ -83,6 +110,68 @@ Example (conceptually):
 
 In eVault, a MetaEnvelope for a post would have `ontology: "550e8400-e29b-41d4-a716-446655440001"`, and its Envelopes would have `ontology` values such as `content`, `authorId`, `createdAt`.
 
+## Proposing a new ontology
+
+Nothing in W3DS obliges you to squeeze your data into an existing type. If no schema fits what you are modelling, the correct move is to **propose a new one** — never to invent a `schemaId` and ship it.
+
+An invented `schemaId` does not fail loudly. The MetaEnvelope is written, the awareness packet fans out, and every receiving platform finds no mapping for that schema and drops it. The data becomes unreachable to the ecosystem while looking perfectly healthy on the platform that wrote it.
+
+### Before proposing
+
+1. `GET /schemas` and search the titles.
+2. `GET /domains/:id/schemas` for the domain your data belongs to.
+3. Read the near misses in full with `GET /schemas/:id`.
+
+Reuse beats addition, and **extending a near match by PR beats creating a parallel type**. Two schemas that mean the same thing split the ecosystem in half: platforms mapping one will not see data from platforms mapping the other.
+
+### Write the schema
+
+Schemas are ordinary files in the [prototype repository](https://github.com/MetaState-Prototype-Project/prototype), under `services/ontology/schemas/<name>.json`. The service loads the directory into an in-memory index at boot; there is no database and no registration call.
+
+```json
+{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "schemaId": "<a freshly generated random UUIDv4>",
+ "title": "Bookmark",
+ "domain": "productivity",
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "format": "uuid",
+ "description": "The unique identifier for the bookmark"
+ },
+ "userId": {
+ "type": "string",
+ "format": "uuid",
+ "description": "The ID of the user who created the bookmark"
+ },
+ "createdAt": {
+ "type": "string",
+ "format": "date-time",
+ "description": "When the bookmark was created"
+ }
+ },
+ "required": ["id", "userId", "createdAt"],
+ "additionalProperties": false
+}
+```
+
+Requirements:
+
+- **`schemaId`** — a freshly generated random UUIDv4 (`uuidgen`, `crypto.randomUUID()`). Never derive one from an existing ID, never continue a numeric sequence you notice in the directory, and never reuse an ID from another schema.
+- **`title`** — the type name as other platforms will search for it. Singular, PascalCase.
+- **`domain`** — one value from the `Domain` schema's enum, fetchable at `GET /domains`. Platforms are granted access domain by domain, so this decides who can consume the type.
+- **`properties`** — every field with a `description`. Each property name becomes an Envelope's `ontology` value in the eVault, so **name fields for their cross-platform meaning, not after your local columns**. `authorId` is a W3DS field name; `fk_user_id_2` is not.
+- **`required`** — the fields a consumer can rely on being present.
+- **`additionalProperties`** — `false`, unless you have a specific reason.
+
+### Open the PR
+
+Add the file, open a pull request against the prototype repository, and say in the description what the type is for and which platform will write it. Reviewers will ask whether an existing schema could have carried the data — answer that question in the PR body and you will save a round trip.
+
+Until the PR merges and the service redeploys, **the type does not exist**. Do not ship a `mapping.json` referencing an unmerged `schemaId`; the sync will look fine locally and silently drop everywhere else.
+
 ## Available schemas
 
 To see all available schemas, call `GET /schemas` on the [Ontology production service](/docs/W3DS%20Basics/Links) or browse the [viewer](https://ontology.w3ds.metastate.foundation/) at the production base URL.
@@ -97,3 +186,4 @@ To see all available schemas, call `GET /schemas` on the [Ontology production se
 - [eVault](/docs/Infrastructure/eVault) — MetaEnvelopes, Envelopes, and the `ontology` field
 - [W3DS Basics](/docs/W3DS%20Basics/getting-started) — Ontology and schema concepts
 - [Links](/docs/W3DS%20Basics/Links) — Production Ontology base URL
+- [Data Ownership Rules](/docs/W3DS%20Basics/Data-Ownership-Rules) — why every persisted entity needs an ontology