From d5d7a222a43fb37662b7f0d125cf0406ba7fdf77 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 5 Jul 2026 02:56:57 +0000 Subject: [PATCH] Establish canonical documentation links --- README.md | 4 ++-- docs/{integrations/http-api.md => api.md} | 6 +++--- docs/cli.md | 4 ++-- docs/config.md | 2 +- docs/consumers/api.md | 2 +- docs/integrations/{narratio.md => subprocess.md} | 14 +++++++------- docs/troubleshooting.md | 2 +- 7 files changed, 17 insertions(+), 17 deletions(-) rename docs/{integrations/http-api.md => api.md} (97%) rename docs/integrations/{narratio.md => subprocess.md} (85%) diff --git a/README.md b/README.md index 2ce6cc9..a67e91c 100644 --- a/README.md +++ b/README.md @@ -26,9 +26,9 @@ This command renders the prepared prompt and effective runtime settings without - [Operations guide](docs/operations.md) - [Troubleshooting](docs/troubleshooting.md) - [Go library package](docs/consumers/pkg-scriptorium.md) -- [HTTP API integration](docs/integrations/http-api.md) +- [HTTP API reference](docs/api.md) - [OpenAI-compatible chat integration](docs/integrations/openai-compatible-chat.md) -- [Narratio subprocess integration](docs/integrations/narratio.md) +- [Subprocess integration](docs/integrations/subprocess.md) - [Architecture policy](docs/policy/architecture.md) ## Examples diff --git a/docs/integrations/http-api.md b/docs/api.md similarity index 97% rename from docs/integrations/http-api.md rename to docs/api.md index 28f510a..72fc075 100644 --- a/docs/integrations/http-api.md +++ b/docs/api.md @@ -1,14 +1,14 @@ -# HTTP API Integration +# HTTP API Reference ## Scope -This document defines the implemented inbound HTTP contract for Scriptorium. +This document is the canonical public HTTP contract for Scriptorium. Current scope is only: - `POST /v1/runs` -For CLI behavior, see the [CLI reference](../cli.md). +For CLI behavior, see the [CLI reference](cli.md). ## Endpoint diff --git a/docs/cli.md b/docs/cli.md index 741a161..b7fb23f 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -20,8 +20,8 @@ go run ./cmd/scriptorium render \ Integration references: -- [HTTP contract](integrations/http-api.md) -- [Narratio subprocess contract](integrations/narratio.md) +- [HTTP API reference](api.md) +- [Subprocess integration](integrations/subprocess.md) ## Common Argument Rules diff --git a/docs/config.md b/docs/config.md index cf4ca3a..820c95c 100644 --- a/docs/config.md +++ b/docs/config.md @@ -328,5 +328,5 @@ examples/schemas/dnd/structured_events.schema.json ## Integration References -- [Inbound HTTP contract](integrations/http-api.md) +- [HTTP API reference](api.md) - [Outbound OpenAI-compatible contract](integrations/openai-compatible-chat.md) diff --git a/docs/consumers/api.md b/docs/consumers/api.md index 3607f37..f7fa87a 100644 --- a/docs/consumers/api.md +++ b/docs/consumers/api.md @@ -3,7 +3,7 @@ Scriptorium can be used by consumers through three implemented surfaces: - CLI commands, documented in [CLI reference](../cli.md). -- HTTP `POST /v1/runs`, documented in [HTTP API integration](../integrations/http-api.md). +- HTTP `POST /v1/runs`, documented in [HTTP API reference](../api.md). - Go package `gitea.maximumdirect.net/eric/scriptorium`, documented in [pkg-scriptorium](pkg-scriptorium.md). The Go package is the typed in-process API. It prepares prompts, runs prompts, accepts file or inline artifacts, supports per-request execution overrides, and exposes stable public errors for `errors.Is`. diff --git a/docs/integrations/narratio.md b/docs/integrations/subprocess.md similarity index 85% rename from docs/integrations/narratio.md rename to docs/integrations/subprocess.md index ea2e3c4..f1f15af 100644 --- a/docs/integrations/narratio.md +++ b/docs/integrations/subprocess.md @@ -1,14 +1,14 @@ -# Narratio Subprocess Integration +# Subprocess Integration ## Purpose -This document defines the supported subprocess contract for Narratio invoking Scriptorium through the public CLI. +This document defines the supported subprocess contract for downstream applications invoking Scriptorium through the public CLI. This is a CLI contract, not an internal Go package integration. ## Supported Commands -Narratio should invoke: +Downstream applications should invoke: - `scriptorium run` - `scriptorium render` @@ -37,7 +37,7 @@ scriptorium render \ --format json ``` -Narratio may add: +Callers may add: - `--config ` - `--profile ` @@ -47,7 +47,7 @@ Narratio may add: ## Config And Directory Behavior -Narratio can rely on resolved app config or pass explicit paths. +Callers can rely on resolved app config or pass explicit paths. - default config search order: 1. `/usr/local/etc/scriptorium/config.yml` @@ -63,7 +63,7 @@ Profile selection follows runner behavior: 2. prompt `default_profile` 3. error if neither is available -Narratio should treat prompt/profile IDs as deployment configuration, not hardcoded logic. +Callers should treat prompt/profile IDs as deployment configuration, not hardcoded logic. ## Input And Variable Contract @@ -91,7 +91,7 @@ Narratio should treat prompt/profile IDs as deployment configuration, not hardco - stdout: prepared-run output unless `--out` is used - stderr: errors -Narratio should capture stdout and stderr separately. +Callers should capture stdout and stderr separately. ## Exit Status Contract diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index c824ff1..d37a73a 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -176,7 +176,7 @@ Relevant links: - [CLI reference](cli.md) - [Configuration reference](config.md) -- [HTTP API integration](integrations/http-api.md) +- [HTTP API reference](api.md) ## Prompt Template Render Failures