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://toystory/character/woody
nap://toystory/location/andys-room
nap://toystory/scene/pizza-planet
nap://toystory/prop/andy-hat

Installation

Installation Script

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

The installation script installs both 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

Quick Start

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

# Initialize with local provider
nap init toystory --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 auth login
nap init --provider portals-cloud

# Inspect or clear the OS-keyring-backed session
nap auth status
nap auth logout

# Check system status
nap status

# Run diagnostics
nap doctor

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

Portals Cloud uses grpcs://lore.portals.works on standard TLS port 443. Login is the only interactive VCS step; repository operations remain noninteractive and return an actionable nap auth login error when credentials are missing or expired. Lore automatically exchanges the eight-hour login session for a five-minute token scoped to the single repository used by init, clone, push, pull, sync, publish, and locking. CI uses a revocable service-account API key exchange; do not store long-lived bearer tokens in CI variables.

nap install lore installs the exact portalshq/lore release compiled into that Nap version. It downloads the installer from the same release tag, verifies its pinned SHA-256 before execution, and explicitly selects the Portals fork. It never executes the mutable main installer or silently falls back to an upstream Lore binary. Production release metadata binds this Lore client version to Nap's signed checksum manifest.

CI reads the API key from its secret store and passes it to Lore over stdin, so the secret is absent from process arguments and command logs:

export PORTALS_CLOUD_API_KEY="${CI_PORTALS_CLOUD_API_KEY}"
nap auth login --api-key

Use --api-key-env NAME to select a different secret environment variable.

Create a Repository

# Initialize a new repository
nap init toystory

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

Create & Inspect Entities

# Create a character
nap create character woody -u toystory -n "Woody"

# Create a location
nap create location andys-room -u toystory -n "Andy's Room"

# Set properties
nap set nap://toystory/character/woody toy_type human
nap set nap://toystory/character/woody homeworld "nap://toystory/location/andys-room"

# Resolve a manifest
nap resolve nap://toystory/character/woody

# Query a specific field
nap resolve nap://toystory/character/woody#properties.toy_type
# → human

# Query a subtree
nap query nap://toystory/character/woody properties

Version Control

# View commit history
nap history nap://toystory/character/woody

# Create branches
nap branch toystory canon

# Sync with remote
nap sync toystory

# Publish to remote
nap publish toystory

Output Formats

nap resolve nap://toystory/character/woody -f json
nap resolve nap://toystory/character/woody -f yaml

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://toystory/character/woody#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 toybox-builders
• 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://toystory/character/woody"
name: "Woody"
entity_type: character
version: 17
properties:
  homeworld: "nap://toystory/location/andys-room"
  toy_type: human
representations:
  reference_image:
    hash: "blake3:e3b0c44..."
    format: png
provenance:
  model: "midjourney-v6"
  prompt_hash: "blake3:abc123..."

3. Commit — History

Commits are content-addressed (BLAKE3) snapshots with patch metadata. Full history and revision identity live in the VCS, keeping manifests bounded and avoiding self-referential revision pointers.

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.

Scene Clips as Representations

Scenes can own generated video clips the same way characters own reference images. A generated clip is not usually a representation of one character; it is a representation of a scene, with references back to the characters, locations, props, and style guides that shaped it.

nap create scene pizza-planet -u toystory -n "Pizza Planet"
nap add nap://toystory/scene/pizza-planet clip-01 ./pizza-planet-clip-01.mp4 --format mp4 -m "Add pizza-planet scene clip"

The scene manifest remains simple and durable:

id: "nap://toystory/scene/pizza-planet"
name: "Pizza Planet"
entity_type: scene
version: 3
properties:
  summary: "Woody and Buzz enter a crowded pizza-planet while searching for passage off Andy's Room."
  time_of_day: night
  mood: tense
references:
  characters:
    - "nap://toystory/character/woody"
    - "nap://toystory/character/buzzlightyear"
  location: "nap://toystory/location/pizza-planet"
representations:
  clip-01:
    hash: "blake3:af1349b9..."
    format: mp4
    uri: "clip-01.mp4"

When resolved with provenance, NAP returns versioned per-file provenance for the manifest and each direct representation. This keeps generation metadata attached to the committed files without requiring users to manage the underlying VCS directly.

nap resolve nap://toystory/scene/pizza-planet --provenance

manifest:
  id: "nap://toystory/scene/pizza-planet"
  name: "Pizza Planet"
  entity_type: scene
  version: 3
  representations:
    clip-01:
      hash: "blake3:af1349b9..."
      format: mp4
      uri: "clip-01.mp4"
provenance:
  revision: "a72c9f3b..."
  files:
    - role: manifest
      path: "scene/pizza-planet.yaml"
      provenance:
        nap.provenance.kind: edit
        nap.provenance.author: toybox-builder
    - role: representation
      name: clip-01
      path: "scene/clip-01.mp4"
      uri: "clip-01.mp4"
      hash: "blake3:af1349b9..."
      format: mp4
      provenance:
        nap.provenance.kind: generation
        nap.provenance.model: video-generator
        nap.provenance.prompt.address: "blake3:b4d2..."

Entity Types

Repository Layout

Each repository is a Git repository on disk:

toystory/                    ← repository root (Git repo)
├── .nap/
│   └── config.yaml          ← repository configuration
├── repository.yaml            ← world manifest
├── characters/
│   ├── woody.yaml
│   └── slinky.yaml
├── locations/
│   └── andys-room.yaml
├── scenes/
│   └── pizza-planet.yaml
└── props/

Representation downloads and presigned URLs

Lore can hydrate arbitrary committed bytes with lore file write. NAP exposes the same binary-safe primitive through VcsBackend::read_file_bytes_at_ref and can create a temporary public URL for a direct representation:

nap presign nap://toystory/character/woody reference_image \
  --branch main \
  --ttl-seconds 900

The representation must have a repository-relative uri, be committed at the selected revision, and have been pushed to the Lore server. Branches are pinned to a commit before NAP resolves the manifest and content address. External URLs, linked repositories, absolute paths, path traversal, URI fragments, and unversioned working-tree files are not supported.

The returned URL is a bearer capability: anyone who has it can download the immutable bytes until it expires. Do not place it in logs, analytics, exception messages, source control, or long-lived storage.

Configuration

For NAP-managed local Lore installations created after this feature, NAP writes a unique presign HMAC key into the owner-only Lore config. Existing configs are not modified automatically. Add a unique 32-byte hex key and restart Lore:

[server.http]
presigned_url_hmac_key = "<64 hex characters>"

Generate a key with openssl rand -hex 32. The HTTP origin defaults to http://127.0.0.1:41339 for local Lore. For an explicitly configured self-hosted deployment, pass --http-url or set NAP_LORE_HTTP_URL.

Authenticated servers also require a repository-scoped bearer token. Set NAP_LORE_HTTP_TOKEN (preferred) or NAP_LORE_GRPC_TOKEN, or point --token-env at another environment variable. Literal token command-line arguments are intentionally unsupported because process listings can expose them.

Portals Cloud status: public presign and redemption ingress is not enabled yet. NAP deliberately does not derive an HTTP endpoint from grpcs://lore.portals.works. Production enablement remains a separately reviewed deployment task.

Rust callers use Resolver::presign_representation. Python exposes synchronous presign_representation, and TypeScript exposes asynchronous presignRepresentation. All return the URL, expiry, pinned revision, repository ID, Lore address, representation name, and format.

MCP Server

The standard NAP installer bundles the native nap-mcp-server binary with nap. If the MCP command is missing or broken, rerun the standard NAP installer from a host shell.

The MCP server is not a daemon; agent clients start it on demand over stdio, and it proxies tool calls to the host nap CLI.

Agent Sandbox Integration

When running inside a sandboxed environment (e.g., Codex) without outbound network access, use MCP tools instead of shelling out to the nap CLI directly. The MCP server runs on the host machine, starts only when the agent/MCP client launches it over stdio, and proxies tool calls to the host nap CLI.

Direct nap CLI examples in this skill are for humans, host-local shells, and non-sandboxed scripts. In an agent sandbox, use the MCP tools for any operation that may need Lore/cloud/network access.

Available MCP Tools

All nap CLI commands are available as MCP tools with nap_ prefix. For example:

• nap resolve -> nap_resolve tool
• nap create -> nap_create tool
• nap set -> nap_set tool

Prefer MCP tools over shell commands when in a sandbox.

MCP Server Configuration

Add to your agent's MCP configuration (e.g., ~/.codex/config.json):

{
  "mcpServers": {
    "nap": {
      "command": "/bin/sh",
      "args": [
        "-lc",
        "NAP_DIR=\"$HOME/.nap\" exec nap-mcp-server"
      ]
    }
  }
}

Connect with Codex

Codex stores MCP configuration in ~/.codex/config.toml alongside the rest of its config. The Codex CLI, the ChatGPT desktop app, and the IDE extension all share that MCP configuration, so you only need to register nap once.

Add the server with the CLI:

codex mcp add nap --env NAP_DIR="$HOME/.nap" -- /bin/sh -lc 'exec nap-mcp-server'

If nap-mcp-server is not on PATH, use the full installed path instead, usually ~/.local/bin/nap-mcp-server or /usr/local/bin/nap-mcp-server.

You can also configure it manually in ~/.codex/config.toml:

[mcp_servers.nap]
command = "/bin/sh"
args = ["-lc", "NAP_DIR=\"$HOME/.nap\" exec nap-mcp-server"]
enabled = true

Project-scoped config works too for trusted projects:

[mcp_servers.nap]
command = "/bin/sh"
args = ["-lc", "NAP_DIR=\"$HOME/.nap\" exec nap-mcp-server"]
enabled = true

Use the same block in .codex/config.toml inside a trusted project if you want the server scoped to that repository.

Other MCP Clients

Claude Desktop and other MCP clients use the same stdio pattern. Add a server entry that runs the bundled nap-mcp-server command on demand, and keep NAP_DIR pointed at your NAP workspace if you need a non-default data directory.

Example host-side launch command:

/bin/sh -lc 'NAP_DIR="$HOME/.nap" exec nap-mcp-server'

Use the same command/args form in any client that supports stdio MCP servers.

Inside sandboxes, use the MCP tools instead of shelling out to nap directly for network-backed operations. Direct nap CLI commands remain the right choice for humans and host-local shells.

NAP CLI Reference

The nap command-line interface (v0.8.1) 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 toystory

# Create an entity
nap create character woody -u toystory -n "Woody"

# Resolve a manifest
nap resolve nap://toystory/character/woody

# Query a subtree
nap query nap://toystory/character/woody properties

# View commit history
nap history nap://toystory/character/woody

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

Portals Cloud presign/redeem HTTP ingress is currently WIP and intentionally unavailable. Setting an HTTP URL is appropriate only when that Lore deployment has explicitly enabled and exposed its presign endpoint.

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 toybox-builders 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