updates: improve NCP validation workflow and adopter docs

.github/workflows/validate-ncp.yml

@@ -0,0 +1,31 @@
+name: Validate NCP
+
+on:
+  pull_request:
+  push:
+    paths:
+      - 'schema/**'
+      - 'examples/**'
+      - 'tests/**'
+      - 'package.json'
+      - 'package-lock.json'
+      - '.github/workflows/validate-ncp.yml'
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install Dependencies
+        run: npm ci
+
+      - name: Validate Canonical Fixtures
+        run: npm run validate:schema

CONTRIBUTING.md

@@ -6,6 +6,12 @@ The **Narrative Context Protocol (NCP)** is the open-source Dramatica storyform
 ## How to Contribute
 We welcome contributions that improve the schema, examples, documentation, and validation tooling. Proposed changes should maintain cross-medium applicability and keep JSON/YAML definitions in sync.
 
+### Example Fixture Policy
+- Keep schema-valid interchange fixtures in `/examples/` (and `/examples/invalid/` for expected-failure tests).
+- Keep historical or migration-only payloads in `/examples/legacy/`.
+- Update `tests/validate-schema.js` whenever fixture coverage changes.
+- Run `npm run validate:schema` before opening a PR.
+
 ## Governance & Review
 NCP was developed in collaboration with the **Entertainment Technology Center (ETC) at the University of Southern California** and is stewarded by **Narrative First** (The Dramatica Co.). Core maintainers lead reviews and incorporate community and partner feedback.
 

HISTORY.md

@@ -26,4 +26,4 @@ Together, this dedicated group is charting a forward-looking path, passionately
 
 ⸻
 
-For a full list of changes and updates, refer to [terminology.md](/terminology.md).
+For canonical terminology updates, refer to the files under [/docs/terminology/](/docs/terminology/).

README.md

@@ -10,7 +10,7 @@ NCP is curated by **The Dramatica Co.**—the merger of **Write Bros. Inc.** and
 
 At its core, NCP provides a **structured yet adaptable schema**, ensuring narratives retain their logical consistency and emotional depth, even when interpreted or extended by numerous interacting agents. By encoding narrative elements into clear, universally understood representations, NCP maintains the original intent of the author throughout dynamic, distributed narrative environments.
 
-Additionally, NCP acts like a "blockchain-for-subtext," transparently tracking narrative contributions, modifications, and creative expansions. This ensures the original artistic voice and intent remain clear and traceable, regardless of the complexity or number of agents involved.
+NCP is transport-focused: it standardizes how storyform context is represented so different tools can exchange the same structural intent without semantic drift.
 
 Built upon proven narrative theories and driven by emerging advancements in AI storytelling, NCP simplifies and standardizes complex narrative exchanges. It empowers storytellers, technologists, and creative communities in film, gaming, literature, interactive media, and generative AI environments to collaborate freely—without sacrificing coherence, authenticity, or the original author's vision.
 
@@ -51,6 +51,32 @@ In 2025, **Write Brothers®**—creators of Dramatica® and Movie Magic Screenwr
 
 Begin by reading the complete [Specification](/SPECIFICATION.md)
 
+Install validation dependencies and run fixture checks:
+
+```bash
+npm install
+npm run validate:schema
+```
+
+`examples/legacy/` contains migration samples and is intentionally excluded from canonical validation.
+`examples/example-mapping.json` is a mapping fragment example, not a full schema document.
+Use [/VALIDATION.md](/VALIDATION.md) for validating your own NCP files and CI setup.
+
+## For Adopters (Self-Serve)
+
+If you found this repository and want to validate your own NCP JSON, do this:
+
+1. Clone this repo and run:
+```bash
+npm install
+```
+2. Validate your file directly against the canonical schema:
+```bash
+npm run validate:file -- /path/to/your-ncp.json
+```
+3. If validation fails, fix the reported fields and run the same command again.
+4. If you maintain your own repository, copy the CI pattern from `/VALIDATION.md` so every PR validates NCP automatically.
+
 ## Repository Structure
 ```
 narrative-context-protocol/
@@ -64,18 +90,23 @@ narrative-context-protocol/
 │   ├── ncp-schema.json
 │   └── ncp-schema.yaml
 ├── examples/
+│   ├── example-story.json
 │   ├── anora.json
 │   ├── the-shawshank-redemption.json
-│   ├── example-story.json
-│   └── example-mapping.json
+│   ├── example-mapping.json
+│   ├── invalid/
+│   │   └── signpost-sequence-out-of-range.json
+│   └── legacy/
+│       ├── anora-legacy.json
+│       └── the-shawshank-redemption-legacy.json
 ├── docs/
 │   ├── terminology/
-│       ├── 01.perspectives.md
-│       ├── 02.appreciations-of-narrative.md
-│       ├── 03.narrative-functions.md
-│       ├── 04.dynamics.md
-│       ├── 05.vectors.md
-│       ├── 10.dramatica-translation.md
+│   │   ├── 01.perspectives.md
+│   │   ├── 02.appreciations-of-narrative.md
+│   │   ├── 03.narrative-functions.md
+│   │   ├── 04.dynamics.md
+│   │   ├── 05.vectors.md
+│   │   └── 10.dramatica-translation.md
 │   └── narrative-context-protocol-schema.md
 ├── tests/
 │   └── validate-schema.js

SPECIFICATION.md

@@ -147,7 +147,7 @@ Clearly differentiating between Subtext and Storytelling enhances narrative clar
 | Represents authorial intent  | Shapes audience experience      |
 | Ensures structural coherence | Allows stylistic and expressive flexibility |
 
-This separation becomes even more critical in the AI era. Training models exclusively on storytelling—whether through transcripts, closed captions, or script dialogue—beyond being unethical--is fundamentally unproductive. Such training is ineffective because it captures only the surface-level "flavoring" of a story, not its underlying thematic essence. The true value resides in the structural coherence provided by subtext, the very heart of the narrative.
+This separation becomes even more critical in AI workflows. Training exclusively on storytelling artifacts captures surface expression, but often misses transferable structural intent. Subtext is the layer designed for durable interchange.
 
 ---
 
@@ -217,7 +217,7 @@ The implications for interactive narratives are significant. In interactive stor
 
 ### Players
 
-Characters whose actions and motivations reveal deeper thematic layers (subtext), moving beyond superficial characterization. Each Player must be  linked explicitly to an **Objective Story Throughline Perspective** to maintain narrative coherence.
+Characters whose actions and motivations reveal deeper thematic layers (subtext), moving beyond superficial characterization. Each Player should be linked to one or more relevant Perspectives to maintain narrative coherence.
 
 ```json
 "players": [

VALIDATION.md

@@ -0,0 +1,105 @@
+# NCP Validation Guide
+
+Use this guide to validate Narrative Context Protocol JSON payloads against the canonical schema.
+
+## First-Time Adopter Checklist
+
+If you discovered NCP and want to validate your own payload quickly, follow this exact sequence:
+
+1. Clone this repository.
+2. Run:
+```bash
+npm install
+```
+3. Validate your file:
+```bash
+npm run validate:file -- /path/to/your-ncp.json
+```
+4. Treat any `FAIL` output as blocking.
+5. Re-run until you get `PASS`.
+
+## Local Setup
+
+```bash
+npm install
+```
+
+## Validate This Repository's Fixtures
+
+```bash
+npm run validate:schema
+```
+
+This validates:
+
+- `/examples/example-story.json`
+- `/examples/anora.json`
+- `/examples/the-shawshank-redemption.json`
+- Expected failures in `/examples/invalid/*.json`
+
+## Validate Your Own NCP File(s)
+
+```bash
+npm run validate:file -- /absolute/or/relative/path/to/your-ncp.json
+```
+
+You can pass multiple files:
+
+```bash
+npm run validate:file -- ./my-story.json ./their-story.json
+```
+
+The command returns non-zero on failure, which makes it CI-friendly.
+
+## Using NCP Validation In Your Own Repository
+
+If you do not want to run validation from this repository, copy these files into your own project:
+
+- `/schema/ncp-schema.json`
+- `/tests/validate-file.js`
+
+Then install Ajv and run:
+
+```bash
+npm install ajv
+node tests/validate-file.js /path/to/your-ncp.json
+```
+
+For continuous enforcement, add the GitHub Actions workflow below.
+
+## Timestamp Rule (`created_at`)
+
+NCP requires `story.created_at` to be an ISO-8601 UTC timestamp in this form:
+
+- `YYYY-MM-DDTHH:MM:SSZ`
+- Example: `2025-12-01T12:34:56Z`
+
+## GitHub Actions (Reference)
+
+If another repository stores NCP files, use this workflow pattern:
+
+```yaml
+name: Validate NCP
+
+on:
+  pull_request:
+  push:
+
+jobs:
+  validate-ncp:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm run validate:file -- path/to/your-ncp.json
+```
+
+## Adoption Recommendations
+
+- Pin the schema version (`schema_version`) in your payloads.
+- Validate NCP during pull requests and before release builds.
+- Keep canonical keys even when using custom mapping namespaces.
+- Treat `/examples/legacy/` as migration reference only, not canonical interchange fixtures.