nap — Narrative Addressing Protocol

NAP is a protocol that makes narrative resources addressable, resolvable, and interoperable across tools, storage systems, formats, and AI workflows.

Characters, locations, scenes, props, and entire fictional repositories — NAP gives each one a stable URI, a human-and-machine-readable manifest, a content-addressed history, and a resolver that connects them all.

In the same way that IPFS content-addressed files and OCI container-addressed images, NAP is narrative-addressed — a universal namespace for the building blocks of stories.

Why NAP?

Today, narrative assets live in silos:

• Worldbuilding docs in Notion or Google Docs
• Character sheets in spreadsheets
• Concept art in Dropbox or S3
• Scene breakdowns in Final Draft or Fade In
• AI prompts scattered across chat logs
• 3D assets on Sketchfab or Polycam

None of these tools talk to each other. NAP unifies them under a single addressing and resolution layer.

nap://starwars/character/lukeskywalker
nap://starwars/location/tatooine
nap://starwars/scene/cantina
nap://toystory/prop/andy-hat

Core Primitives

NAP is built on four primitives:

1. URI — Identity

A nap:// URI identifies any narrative resource. Version and branch are orthogonal selectors passed alongside the URI — never encoded in the path (mirrors Git, OCI, and package managers).

nap://starwars/character/lukeskywalker#references.appears_in
────┬── ───┬──── ────┬──── ──────┬────── ─────────────┬───────────
 scheme repository  entity_type entity_id          fragment (query)

2. Manifest — Current State

A YAML manifest is the durable representation of a narrative resource. It is simultaneously:

• Human-editable — readable by worldbuilders
• Machine-editable — structured, schema-validated
• Agent-readable — subtree-queryable for AI workflows
• Portable — no runtime dependency, just a file
• Signable — hash the content, sign the hash (Ed25519 in v0+)
• Versionable — the manifest is what gets committed

id: "nap://starwars/character/lukeskywalker"
name: "Luke Skywalker"
entity_type: character
version: 17
properties:
  homeworld: "nap://starwars/location/tatooine"
  species: human
representations:
  reference_image:
    hash: "sha256:e3b0c44..."
    format: png
provenance:
  model: "midjourney-v6"
  prompt_hash: "sha256:abc123..."
head: "a72c9f3b..."

3. Commit — History

Commits are content-addressed (BLAKE3) snapshots with patch metadata. The manifest stores only head — a pointer to the latest commit. Full history lives in the VCS, keeping manifests bounded.

4. Resolver — URI → Manifest

The resolver turns a nap:// URI into a manifest (or a subtree of one). With optional selectors for branch or commit hash, it supports versioned resolution and fragment-based queries for efficient data access.

Entity Types

Repository Layout

Each repository is a Git repository on disk:

starwars/                    ← repository root (Git repo)
├── .nap/
│   └── config.yaml          ← repository configuration
├── repository.yaml            ← world manifest
├── characters/
│   ├── lukeskywalker.yaml
│   └── darthvader.yaml
├── locations/
│   └── tatooine.yaml
├── scenes/
│   └── cantina.yaml
└── props/

Installation

Installation Script

curl -fsSL https://github.com/portalshq/narrativeengine/releases/latest/download/install.sh | bash

The installation script installs both native binaries: nap and nap-mcp-server. The MCP server is dormant by default; agent clients start it on demand over stdio so sandboxed agents can use NAP through host-side CLI proxy calls.

Skills Install

Install these skills to use NAP with agent workflows, including entity-aware prompts, generation templates, and the resolve/update steps that keep character and scene output consistent.

npx skills add portalshq/narrativeengine

CLI & Server (Rust — compile from source)

git clone https://github.com/cinematiccanvas/nap.git
cd nap
cargo build --release

# Binaries land in target/release/
#   nap          — CLI tool
#   nap-server   — HTTP resolver server

Python SDK (prebuilt wheel, no Rust needed)

pip install narrativeengine

from narrativeengine import create_block, generate_candidate, render_lore_summary

block = create_block("char-1", "A brave adventurer")
candidate = generate_candidate(block)

TypeScript SDK (prebuilt binary, no Rust needed)

npm install @portalshq/narrativeengine

import { createBlock } from "@portalshq/narrativeengine";

const block = createBlock("char-1", "A brave adventurer");

Quick Start

# Initialize a repository (prompts for provider on first run)
nap init starwars

# Initialize with local provider
nap init starwars --provider local

# Configure provider only (no repository)
nap init --provider local

# Initialize with remote provider
nap init --provider remote --remote-url lore://localhost:41337 --workspace-id my-workspace

# Initialize with Portals Cloud
nap init --provider portals-cloud

# Check system status
nap status

# Run diagnostics
nap doctor

# Run diagnostics with auto-repair
nap doctor --repair

Create a Repository

# Initialize a new repository
nap init starwars

# See what you created
ls starwars/
# → .nap/  repository.yaml  characters/  locations/  scenes/  props/

Create & Inspect Entities

# Create a character
nap create character lukeskywalker -u starwars -n "Luke Skywalker"

# Create a location
nap create location tatooine -u starwars -n "Tatooine"

# Set properties
nap set nap://starwars/character/lukeskywalker species human
nap set nap://starwars/character/lukeskywalker homeworld "nap://starwars/location/tatooine"

# Resolve a manifest
nap resolve nap://starwars/character/lukeskywalker

# Query a specific field
nap resolve nap://starwars/character/lukeskywalker#properties.species
# → human

# Query a subtree
nap query nap://starwars/character/lukeskywalker properties

Version Control

# View commit history
nap history nap://starwars/character/lukeskywalker

# Create branches
nap branch starwars canon

# Sync with remote
nap sync starwars

# Publish to remote
nap publish starwars

Output Formats

nap resolve nap://starwars/character/lukeskywalker -f json
nap resolve nap://starwars/character/lukeskywalker -f yaml

NAP CLI Reference

The nap command-line interface (v0.5.3) provides tools for creating, resolving, and managing narrative resources using the Narrative Addressing Protocol.

Command Overview

Global Options

Output Formats

Most commands support --format (-f) with values yaml (default) or json.

When stdout is not a terminal, JSON is used automatically. Override with $NAP_OUTPUT.

Common Examples

# Initialize a repository
nap init starwars

# Create an entity
nap create character lukeskywalker -u starwars -n "Luke Skywalker"

# Resolve a manifest
nap resolve nap://starwars/character/lukeskywalker

# Query a subtree
nap query nap://starwars/character/lukeskywalker properties

# View commit history
nap history nap://starwars/character/lukeskywalker

HTTP Server

The NAP resolver server provides a REST API for resolution and commits.

# Start the server (defaults to port 3100, base path = current directory)
nap-server

# Custom port and base path
NAP_PORT=8080 NAP_BASE_PATH=/path/to/repositories nap-server

Configuration

NAP core uses environment variables for configuration. All variables serve specific purposes with minimal overlap.

Storage Configuration

Lore VCS Configuration

Constants

Note: The environment variable NAP_DIR (storage base directory) and the constant NAP_DIR (metadata directory name) serve different purposes and do not overlap.

Endpoints

Query parameters for resolution: branch, commit, path (subtree query).

CLI Command Reference

Complete reference for all nap CLI commands.

Design Principles

1. Content-addressed — Every piece of content is identified by its cryptographic hash. Manifests are immutable once committed.

2. URI-addressed — Every entity has a stable, portable URI. URIs are never invalidated by renames or moves.

3. Human-readable — YAML manifests are readable by worldbuilders and AI agents alike.

4. Portable — No runtime dependencies. A manifest is just a YAML file. A repository is just a Git repo.

5. AI-native — Subtree queries let AI agents fetch exactly the data they need. Provenance tracking records generation metadata.

6. Schema-validated — All manifests conform to a JSON Schema. Invalid manifests are rejected at commit time.

7. Decentralized — Repositories are Git repositories. They can be cloned, forked, merged, and published independently.

8. Extensible — New entity types, representation formats, and merge strategies can be added without breaking existing data.

Status

This is a v0 prototype. APIs and formats may change.

License

MIT

Status

This is a v0 prototype. APIs and formats may change.

License

MIT