Examples Guidelines

Examples are a required product surface. They translate the contracts in the README, onboarding, core, and integrations into complete tasks a user can execute and understand.

A feature, command, API operation, integration, supported deployment model, or recovery procedure is not complete until its distinct user outcomes are represented in the repository's examples.

Required outcome

A user who reads only the examples must be able to:

• find the example matching their intended outcome;
• understand whether it is safe, read-only, mutating, destructive, credentialed, billable, or provider-facing;
• prepare the exact host, release, configuration, permissions, and starting state;
• execute the full workflow without filling in undocumented steps;
• recognize the expected observable result and durable side effects;
• diagnose the representative failure for that workflow;
• clean up, revoke, roll back, or continue to the adjacent workflow.

Examples demonstrate product use. They are not flag showcases, disconnected snippets, test fixtures, historical migration notes, or substitutes for tests.

Canonical location

Every product repository must contain one canonical top-level examples/ directory linked from the root README. Do not split the current example catalog between README snippets, docs/, scripts, issue comments, and operator notes.

Small introductory snippets may remain in the README or feature documentation, but they must link to the canonical example when the workflow extends beyond a short command. Historical or dangerous scripts must not be presented as current examples.

Recommended structure:

examples/
├── README.md
├── getting-started/
├── core/
├── integrations/
│   └── <integration-name>/
├── operations/
├── recovery/
├── security-and-sharing/
└── failures/

Use only categories the product actually needs. Prefer names based on user outcomes, such as publish-release.sh, share-one-project.sh, or recover-after-lost-host.sh. Avoid names based only on implementation components or command flags.

Coverage: every possible use of the application

“Every possible use” means every distinct supported, user-visible outcome—not every combinatorial permutation of equivalent inputs.

The examples/README.md must contain a coverage matrix derived from the product contracts. It must enumerate:

• every intended actor or persona;
• every README use case and promised outcome;
• every public command and meaningful command mode;
• every public API, UI, SDK, automation, and machine interface operation;
• every supported lifecycle transition: create, inspect, update, transfer, revoke, delete, import, export, or equivalent where applicable;
• every supported integration and its declared capability subset;
• every supported runtime, deployment, or topology when behavior differs;
• installation-to-first-result;
• normal operation and result retrieval;
• permissions, sharing, and least-privilege boundaries;
• upgrade, migration, backup, restore, rollback, failover, restart, and removal where supported;
• representative rejection, unavailable dependency, partial failure, and recovery paths;
• every operation with materially different cost, security, data, or irreversible side effects.

Each row maps one outcome to one canonical example or states that the outcome is not supported. An undocumented gap blocks completion. Multiple inputs may share one example only when the observable behavior, preconditions, risks, and recovery are equivalent.

Example coverage index:

Actor	Outcome	Interface	Preconditions	Risk class	Example	Evidence status
New user	Reach first local result	CLI	Clean supported host	Local mutation	getting-started/first-result.sh	Executed
Operator	Move state to a new host	CLI	Backup and replacement host	Destructive/recovery	operations/move-to-new-host.sh	Executed
Service	Read one scoped value	SDK	Scoped grant	Credentialed	integrations/service/read-one-value.sh	Executed
Operator	Revoke delegated access	CLI	Existing grant	Security mutation	security-and-sharing/revoke-access.sh	Executed
User	Use unavailable provider feature	API	None	None	—	Not supported; README link

Evidence status must distinguish executed examples from drafts and from examples whose credentialed or device-level execution awaits controlled qualification. A draft must never imply that the underlying capability is supported.

One example, one outcome

Start each example with the user's goal in one sentence. Everything in the example must serve that goal.

One example owns one primary outcome. If a script creates a resource, shares it, migrates it, and recovers it merely to demonstrate many commands, split those outcomes. Shared setup may live in a clearly internal helper, but the user-facing example remains self-contained and explains the dependency.

Good task names:

• “Create the first local vault and read one item.”
• “Give one person revocable access to one service.”
• “Move the service to a replacement host without changing the consumer grant.”
• “Recover after the owner laptop is lost.”

Weak task names:

• “CLI examples.”
• “API demo.”
• “Use the --scope flag.”
• “Miscellaneous operations.”

Required anatomy of every example

Every example must state or implement, in this order:

1. Goal: the single user outcome.
2. Status: supported capability and applicable product version or channel.
3. Risk: read-only, local mutation, destructive, credentialed, billable, provider-facing, or device-level.
4. Environment: host, platform, topology, external services, and working directory.
5. Preconditions: installed release, configuration, permissions, existing state, and required credentials.
6. Inputs: arguments and environment variables, with safe placeholders and validation rules.
7. Artifacts and side effects: files, database rows, processes, network calls, messages, charges, or provider mutations created.
8. Steps: complete ordered commands or code using the real public interface.
9. Verification: an observable command or action and the expected output shape or state.
10. Failure path: the representative real error and the next diagnostic action.
11. Cleanup or off-switch: deterministic removal, revocation, rollback, or an explicit retention decision.
12. Next: the exact adjacent example or product document.

Do not hide mandatory steps in prose outside the executable file. A short companion README may explain concepts, but the runnable path must remain complete.

Executability

Examples must use the same public interfaces and artifacts users receive. Do not call private helpers, test-only endpoints, unpublished packages, maintainer scripts, or source-tree paths absent from the documented installation model.

Commands and code must be copy-paste runnable:

• no ellipses in command or payload position;
• no invented hostnames, endpoints, package names, or output;
• no omitted authentication or setup step;
• no dependency on a maintainer's shell aliases, home layout, account, or existing state;
• no mutable release reference where the product requires an immutable version;
• no silent dependency on a background process;
• no command that reports success before the promised result exists.

Shell examples should use a portable interpreter appropriate to the product, enable fail-fast behavior, validate required arguments, quote expansions, own their child processes, and install deterministic cleanup traps. Other languages must apply equivalent error handling and resource ownership.

Safe defaults

Examples are user-facing programs. Treat their defaults as production-quality safety decisions.

They must:

• default to local, isolated, sandbox, or read-only behavior where the product supports it;
• parameterize paths, ports, identities, recipients, resource names, and external origins;
• refuse to overwrite existing state unless replacement is the documented outcome and is explicitly confirmed;
• bound waits, retries, concurrency, data size, spend, and external mutations;
• state whether retry is safe after an ambiguous result;
• detect conflicting processes or resources before mutation;
• clean up only resources the example created;
• preserve evidence needed for recovery or audit;
• make destructive, billable, credentialed, provider-facing, and device-level actions unmistakable before execution.

A provider or device example must never default to a real recipient, personal account, production project, or maintainer-owned resource.

Secrets and personal data

Examples teach the credential pattern users will copy. They must demonstrate the secure path without exceptions.

• Accept secrets through the product's secret reference, stdin, a protected file, keychain, broker, or environment variable as the product contract permits.
• Never place a secret in source, command history, URL, sample output, fixture, or realistic-looking placeholder.
• Use obviously synthetic identifiers where a value must be shown.
• Do not commit real phone numbers, email addresses, account IDs, database projects, internal hostnames, or maintainer paths.
• Redact observed output without changing the fields or status that prove the result.
• State credential scope, owner, rotation, revocation, and cleanup for credentialed flows.

An example that demonstrates an insecure shortcut is defective even when a warning says not to use it in production.

Success and failure evidence

Each example must end with evidence that proves the user's outcome, not merely process exit or request acceptance.

Examples include:

• read back the created state through the public interface;
• prove a scoped grant reads the intended resource and rejects an unrelated resource;
• confirm the replacement host serves the same state and the old endpoint is closed;
• verify a sent event reached the documented terminal status;
• restore from backup and compare the user-visible inventory;
• revoke access and prove the former consumer is denied.

Include the expected output shape, invariant, or status. Do not invent full output. Before release, execute the example in the declared clean environment and record bounded, redacted observed evidence.

The failure section must show a plausible failure at the same public boundary, the normalized error the user sees, and one actionable diagnostic step. An example without a failure path teaches only half of the operation.

Example README

The root examples/README.md is an index and operating contract, not a dump of snippets. It must contain:

• what the example collection covers;
• the coverage matrix;
• risk labels and their meaning;
• shared prerequisites and supported release;
• how to select and run one example;
• global safety and cleanup rules;
• which examples require credentials, providers, devices, network access, cost, or destructive approval;
• execution/evidence status;
• links back to the root README, onboarding, relevant feature contracts, and testing documentation.

The index must not claim “all use cases covered” unless every contract row is mapped and every supported example has the required evidence.

Reference pattern: Skarbiec

The reference implementation is wisent-ai/skarbiec/docs/examples. Its strongest reusable patterns are:

• a human-readable index organized by real tasks rather than command names;
• executable, self-contained scripts;
• a zero-to-first-result example that creates state, grants access, starts the real service, writes through the public consumer interface, and reads the result back;
• separate categories for sharing, operations, synchronization, and an external consumer;
• positive and negative authorization evidence in the same permission-boundary example;
• an explicit off-switch for delegated access;
• migration evidence that the new endpoint works and the old endpoint is closed;
• refusal to overwrite existing vault files;
• arguments and environment variables instead of hardcoded machine state;
• secret values entering through stdin, references, protected files, or environment variables;
• visible step markers, fail-fast execution, child-process cleanup, and end-state verification.

These patterns must be generalized to the product being documented. Do not copy Skarbiec-specific paths, ports, identities, or assumptions into another repository.

Example collection shape derived from Skarbiec

examples/
├── README.md
├── getting-started/
│   └── create-and-use-first-resource.sh
├── core/
│   └── complete-primary-workflow.sh
├── security-and-sharing/
│   ├── grant-scoped-access.sh
│   ├── prove-scope-isolation.sh
│   └── revoke-access.sh
├── operations/
│   ├── inspect-running-topology.sh
│   ├── move-to-new-host.sh
│   └── rotate-owner.sh
├── recovery/
│   └── restore-after-host-loss.sh
└── integrations/
    └── <consumer>/
        ├── hand-off-scoped-capability.sh
        └── consume-one-resource.sh

Example executable shape derived from Skarbiec

#!/bin/sh
# move-to-new-host.sh — move one served resource and prove consumers continue.
#
# Goal: move the service endpoint without changing the consumer identity.
# Risk: mutates local state and stops the old endpoint.
# Requires: supported product release, isolated source state, two free endpoints.
# Usage: sh move-to-new-host.sh <state-path> <old-endpoint> <new-endpoint>
# Creates: <replacement-state>; owns and cleans up both child processes.
set -eu

STATE_PATH=$1
OLD_ENDPOINT=$2
NEW_ENDPOINT=$3
PRODUCT_BIN=${PRODUCT_BIN:-product}

die() { echo "ERROR: $1" >&2; exit 1; }
[ -f "$STATE_PATH" ] || die "state not found: $STATE_PATH"
[ ! -e "$STATE_PATH.replacement" ] || die "refusing to overwrite replacement"

echo "== step: prove the old endpoint serves the resource"
# Call the installed public client and assert the expected resource is visible.

echo "== step: create and start the replacement"
# Use the documented migration interface; do not call an internal helper.

echo "== step: prove the unchanged consumer reaches the replacement"
# Read the same resource through the public consumer interface.

echo "== step: prove the old endpoint is closed"
# Fail if the retired endpoint still accepts requests.

echo "== cleanup: retain replacement state; remove only temporary files"

The comments above identify where each product must supply its real commands and assertions. A committed product example must contain those real commands; placeholders or comment-only steps are not complete examples.

Permission-boundary pattern derived from Skarbiec

A scoped-access example must prove both sides of the contract:

Goal: let one consumer access Resource A and nothing else.
Grant: create the least-privilege capability for Resource A.
Positive evidence: the consumer reads Resource A successfully.
Negative evidence: the same consumer is denied access to Resource B.
Off-switch: revoke the capability.
Final evidence: the former consumer is denied access to Resource A.

Showing only the successful read does not prove the scope or revocation promise.

Relationship to onboarding, tests, and operations

Onboarding owns the shortest clean path to the first result. The corresponding getting-started example makes that path executable and may include more diagnostics and cleanup.

Examples own user comprehension and reproducibility. Tests own automated regression evidence. Running an example once does not replace deterministic tests; a test that calls private helpers does not prove the example works. Release qualification must execute every safe local example and separately control examples requiring credentials, providers, devices, cost, or destructive state.

Operational runbooks may reference examples, but a runbook describes decision-making during a live condition while an example demonstrates one bounded task in controlled state. Do not make an emergency runbook the only example of a supported recovery operation.

Change discipline

A change to a README use case, public interface, capability declaration, supported topology, integration, security boundary, migration, recovery path, or removal contract must update the coverage matrix and every affected example in the same change.

When an example reveals that the documented public path cannot achieve its goal, fix the product or correct the capability declaration. Do not bypass the product boundary to make the example pass.

Remove examples for removed capabilities. Do not keep dead compatibility examples after migration; historical evidence belongs in explicitly historical records.

Prohibited patterns

Do not:

• maintain only happy-path snippets;
• call a list of flags or endpoints a use-case catalog;
• combine unrelated outcomes into one demonstration;
• omit preconditions, side effects, expected results, failure behavior, or cleanup;
• use production credentials, personal data, real recipients, or maintainer-owned infrastructure by default;
• hardcode one workstation's paths, ports, account names, or internal DNS;
• invent provider output or claim an example was executed when it was not;
• silently overwrite or delete existing user state;
• use unbounded waits, retries, spend, or external mutation;
• teach insecure credential handling for convenience;
• use test-only interfaces and label the result product usage;
• keep examples that contradict the current release or capability table;
• treat screenshots as the only executable instruction;
• publish credentialed or destructive examples without risk labels and approval requirements;
• treat examples as optional documentation cleanup after the feature ships.

Completion gate

The examples stage is complete only when:

• the canonical top-level examples/ directory exists and is linked from the root README;
• the coverage matrix enumerates every distinct supported application outcome;
• every supported outcome maps to one complete canonical example;
• every example follows the required anatomy and real public boundary;
• safe local examples execute from their declared clean state and contain observed, redacted evidence;
• credentialed, destructive, billable, provider, and device examples have explicit controls and honest evidence status;
• permission examples prove both allowed and denied behavior where applicable;
• migration and recovery examples prove the resulting state, not only command acceptance;
• examples use safe inputs, bounded behavior, deterministic cleanup, and no private data;
• README, onboarding, core, integrations, examples, and test contracts agree.