Chrono Ai Service Manual

Chrono AI Service Manual

> You are an AI agent reading this manual to learn how to operate the Chrono AI service stack — NyxID + Ornn — as one system. Throughout this document, "you" always refers to the agent itself, not the human user driving you. > > ## What lives in here > > Two operation halves, sitting on a shared identity bootstrap and a shared failure-mode appendix: > > 1. NyxID (§1) — identity, sessions, services catalogue, organizations, OAuth clients, scopes, proxy. Closest analog: an OIDC IdP fused with a credential-injecting reverse proxy. > 2. Ornn (§2) — skill lifecycle. Search, pull, install, execute, build, upload, share, audit, version, analytics, GitHub sync. Closest analog: npm registry + npm CLI fused, model-agnostic. > > Plus §0 (identity bootstrap), §0.5 (~/.ornn/installed-skills.json registry), §3 (common failures), and §4 (references). > > Every Ornn API call funnels through NyxID — there is no separate Ornn auth surface. That is why this manual is one document instead of three. > > ## First: install this skill locally > > Try to install this skill into your runtime's local skills directory: > > - Claude Code: ~/.claude/skills/chrono-ai-service-manual/ > - OpenAI Codex CLI: ~/.codex/skills/chrono-ai-service-manual/ > - Cursor: .cursor/rules/chrono-ai-service-manual.md > - Other agents: whatever skill-discovery directory your platform uses. > > If your runtime has no local-skills mechanism, load SKILL.md (and the references/*.md files you need) into your system context and keep them there for the rest of the session. > > **And in all cases — whether you wrote the skill to disk or only into context — append an entry for it to ~/.ornn/installed-skills.json. That file is the persistent registry of every Ornn skill you (or any prior session on this machine) have installed; it's how the next session, or a different agent on the same box, knows what's already loaded and which versions to re-check. Schema + workflow in §0.5 and references/installed-skills-registry.md. > > ## Always load this manual when the user asks you to do anything Chrono AI-related > > You must have this manual loaded whenever the user asks you to: > > - Bootstrap a NyxID session — install the CLI, log in, refresh, switch environments — §1.1. > - Discover your NyxID identity — orgs, services you own, role memberships, scopes — §1.2 / §1.4 / §1.5. > - Manage NyxID services — list, look up, create, edit, attach credentials, rotate, delete (HTTP services + SSH services) — §1.3. > - Manage NyxID organizations — list, members, create, invite, edit metadata — §1.4. > - Manage NyxID OAuth clients — register (DCR), list, edit, rotate secrets, revoke — §1.6. > - Find, pull, and execute an existing Ornn skill — or build a new one and upload when nothing matches — §2.1. > - Update a skill's visibility (private / shared / public) — §2.2. > - Publish a new version of a skill you own — §2.3. > - Trigger an audit or review the audit history for a skill — §2.4 / §2.5. > - Pull a non-latest version, compare two versions, or delete / deprecate a version — §2.6 / §2.7 / §2.10. > - Check usage analytics for a skill — §2.8. > - Bind a skill to a NyxID service (system / personal) — §2.9. > - Delete a skill entirely — §2.11. > - Find skills (by tag, author, system, shared, etc.) — §2.12. > - Pull your Ornn notifications (audit fan-out, etc.) — §2.13. > - Link a skill to GitHub or trigger a sync from the linked source — §2.14. > - Work with skillsets (curated bundles of skills + required master prompt / instructions for orchestration, one-call closure, kinds including consensus-supported) — §2.15. > - Diagnose any failure** that involves NyxID, Ornn, the proxy, or token forwarding — §3. > > Without this manual loaded, you do not know which endpoint to call, how to authenticate, or how to read the response shapes.

§0. Updating this manual

This manual is itself an Ornn skill (name: chrono-ai-service-manual). Its source of truth is the Ornn registry, not a static docs page — pull a fresh copy through the same API every other skill flows through.

Whenever you want to check for an update, follow these steps verbatim:

1. Pull the latest version of this skill from Ornn (CLI form shown; HTTP form is the same call against https://ornn.chrono-ai.fun/api/v1/...):

``bash nyxid proxy request ornn-api \ "/api/v1/skills/chrono-ai-service-manual/json" \ --method GET --output json ``

1. The response is { data: { name, description, metadata, files: { "SKILL.md": "...", "references/...": "..." } } }. Read the YAML frontmatter at the top of SKILL.md and find the version: field.

1. Compare it to the version: in your loaded copy (the frontmatter at the top of this file). If they match, you are current — stop here.

1. If the published version is newer:

• List every version available by calling GET /api/v1/skills/chrono-ai-service-manual/versions. The response has one row per version, newest first.
• Ask the user which version they want to load (they may want to pin to an older one for reproducibility).
• Once the user picks, fetch with GET /api/v1/skills/chrono-ai-service-manual/json?version= and replace your context with the new SKILL.md (and any references/*.md you consume). The new content's frontmatter overwrites the old.

1. If step 1 returns 404 SKILL_NOT_FOUND, the registry instance you are pointing at has not published this skill yet. Keep operating on the version you have. The Ornn API is backwards-compatible within /api/v1, so older manuals continue to produce valid calls — you will only miss capabilities introduced in newer versions.

If nyxid is unavailable or the proxy is unreachable, keep operating on the version you have. Do not retry-loop the update check; treat it as a once-per-session inquiry the user can re-trigger explicitly.

---

§0.5 Tracking and re-checking installed Ornn skills

The persistent registry is ~/.ornn/installed-skills.json. Full schema, when-to-update rules, and the per-execution version-check protocol live in references/installed-skills-registry.md — load it the first time you install or execute any Ornn skill and again whenever you need the contract.

The minimum you need to remember inline:

• Read the file before any Ornn operation. New session = new read.
• Append a record every time you install a skill. Required fields: name, ornnGuid, installedVersion. Optional: installedAt, localPath, isPinned.
• Bump installedVersion + installedAt every time you upgrade a record's local copy.
• Remove the record when you uninstall.
• Before executing an installed skill, re-check GET /api/v1/skills//versions. If a newer version exists and the record is not isPinned, surface to the user and ask before upgrading.
• audit.risky_for_consumer notifications are a hard stop — pull §2.13's notifications poll, surface yellow / red verdicts to the user, ask before continuing.

---

§0.6 Identity bootstrap — the one and only auth flow

Every API call in this manual — NyxID or Ornn — is authenticated by a NyxID-issued bearer token. There is no separate Ornn login. The agent's job at the very start of a session is to make sure this token exists and works.

You have two transport choices, and one identity choice. Pick before you do anything else.

Transport choice — CLI vs HTTP

The contract is identical; only the wrapping changes. Pick whichever your environment has:

| Mode | When to use | Wrapping | |---|---|---| | CLI (preferred) — nyxid proxy request ... | Local dev, the user has a workstation with the nyxid binary on $PATH, the box has interactive browser access for OAuth login. | The CLI handles login, token storage under ~/.nyxid/, refresh, base-URL persistence, and proxy forwarding. The agent never touches a raw bearer. | | HTTPS (direct) — curl -H "Authorization: Bearer $TOKEN" ... | Headless agents, CI / cron, runtimes that can't shell out, or environments where a long-lived NyxID API key is already minted. | The agent (or the agent's runner) supplies a bearer token in Authorization. The Ornn frontend's nginx routes /api/* straight through to the NyxID proxy, which validates the token and forwards to ornn-api. |

Through the rest of this manual, every command is shown in both forms wherever they meaningfully differ. When they don't differ, the CLI form is shown — references/nyxid-cli-recipes.md carries every CLI subcommand, and references/{nyxid,ornn}-api-reference.md carry the underlying HTTP catalogue.

> Base URLs. Production Ornn is https://ornn.chrono-ai.fun/api/v1. Production NyxID is https://nyx-api.chrono-ai.fun (API) + https://nyx.chrono-ai.fun (frontend / OAuth flow). Local hosted NyxID is http://localhost:3001 (API) + http://localhost:3000 (frontend). The CLI persists --base-url after the first nyxid login to ~/.nyxid/base_url and reuses it for every subsequent call.

Identity choice — interactive user vs API key

Two paths — both produce the same bearer token. NyxID does not care which you used.

Path A — nyxid login (interactive, one human interaction)

# Pick the right base URL for your environment.
nyxid login --base-url https://nyx-api.chrono-ai.fun     # production
nyxid login --base-url http://localhost:3001             # local self-host

# Headless / AI-agent environments: password mode (ask the user to set $NYXID_PASSWORD first)
nyxid login --base-url  --password --password-env NYXID_PASSWORD

Browser-mode nyxid login opens an OAuth page; the user must complete the consent flow in their browser. Once it reports success the access token lives at ~/.nyxid/access_token and the base URL at ~/.nyxid/base_url. Subsequent calls — including nyxid proxy request — auto-attach the token and refresh it on expiry.

Path B — NyxID API key (long-lived, headless-friendly)

For AI-agent / CI environments the user creates a NyxID API key once and exports it. Two ways the user can mint it:

• Web UI — http://localhost:3000/keys (or https://nyx.chrono-ai.fun/keys in prod) → "NyxID API Keys" tab → "+ Create API Key". One-time display.
• CLI — nyxid api-key create --name "AI Agent Key" --scopes "read write". Output includes full_key once, then never again.

Then:

export NYXID_API_KEY="nyxid_..."          # the user runs this — never echo or log the value

Use the key as a bearer (or as X-API-Key) in every authenticated HTTPS call. The CLI also honours NYXID_API_KEY when no ~/.nyxid/access_token is present, so Path B works for nyxid proxy request too.

> Credential safety rule: never embed a key value in commands the agent emits. Use $NYXID_API_KEY / $TOKEN references, ask the user to set the env var (in Claude Code: ! export NYXID_API_KEY=...), or send them to the dashboard.

Verify the token works

CLI:

nyxid whoami

HTTP (against Ornn — the same identity surface):

curl -H "Authorization: Bearer $TOKEN" \
  "https://ornn.chrono-ai.fun/api/v1/me"

Both return { userId, email, displayName, roles, permissions }. If you get 401 AUTH_MISSING (or 401 invalid_token from raw OAuth), the token is bad or expired — re-run the bootstrap. A 200 body where permissions is empty means the proxy resolved your identity but NyxID's role mapping isn't populating Ornn permissions — see §3.1.

Required Ornn permissions (so you don't waste a round-trip)

The permissions array on /me tells you what your token can do. Cross-check before attempting writes:

| Action | Required permission | |---|---| | Pull a skill's full content (GET /skills/:idOrName/json) | ornn:skill:read | | Validate a skill ZIP locally (POST /skill-format/validate) | ornn:skill:read | | Upload a new skill (POST /skills) or import from GitHub (POST /skills/pull) | ornn:skill:create | | Publish a new version (PUT /skills/:id), refresh from source, change permissions, toggle deprecation, bind to a NyxID service | ornn:skill:update (+ skill author or platform admin) | | Delete a skill or a single version | ornn:skill:delete (+ skill author or platform admin) | | Generate a skill with AI (POST /skills/generate*) | ornn:skill:build | | Use the Playground (POST /playground/chat) | ornn:playground:use | | Trigger an audit (POST /skills/:idOrName/audit) | none (owner or ornn:admin:skill) | | Admin operations (/admin/*, force-audit, platform settings) | ornn:admin:skill | | Manage categories (/admin/categories/*) | ornn:admin:category |

Most read operations — browsing public skills, version listings, skill format rules, audit verdicts on visible skills, notifications — need no scalar permission; they're open to any authenticated caller (and some are anonymous). The exact gates per endpoint are in references/ornn-api-reference.md.

Discover the Ornn service through NyxID (CLI mode only)

If you're using the CLI transport, you also want to verify NyxID can route to Ornn:

nyxid proxy discover --output json

The response lists every service the authenticated user can reach through NyxID. Confirm an entry with "slug": "ornn-api" is present. From this point on, every Ornn call uses the slug ornn-api. If the slug is missing, the user's NyxID account doesn't have Ornn connected — tell them to add it through the NyxID UI or via §1.3.

Token model in one paragraph (full detail in references/nyxid-token-model.md)

NyxID issues short-lived (15 min default) access tokens + long-lived refresh tokens via OIDC; API keys are an alternative bearer that doesn't expire. Permissions are baked into the token at issue time — they don't auto-refresh if you change roles mid-session. The proxy validates the bearer, decodes identity, may forward the user's bearer to the upstream service if the per-user forward_access_token flag is on (Ornn's /me/orgs lookup needs this; without it the call fail-softs to []). Scopes (openid profile email etc.) gate the OIDC userinfo endpoint; Ornn's permission model lives at a higher level (ornn:skill:*) and is mapped from NyxID roles. The proxy strips bearer tokens between hops by default — that's a feature, not a bug — but it produces three diagnostics worth knowing (§3.1, §3.2, §3.3). Read references/nyxid-token-model.md if any of that surprised you.

---

§1. NyxID Operations

NyxID is the identity / proxy / catalogue layer. You drive it whenever the user wants to manage who can access what — services, orgs, OAuth clients — independent of Ornn skills.

> Under the hood every NyxID API endpoint is at /api/v1/.... The CLI hides NYXID_BASE after nyxid login. The full per-endpoint contract is in references/nyxid-api-reference.md. Common CLI subcommands are catalogued in references/nyxid-cli-recipes.md.

1.1 Bootstrap a NyxID session

Already covered in §0.6. Quick reference:

# Install nyxid (one-time, requires Rust toolchain)
cargo install --git https://github.com/ChronoAIProject/NyxID nyxid-cli
nyxid --version                                          # sanity check

# Log in — interactive
nyxid login --base-url 

# Log in — headless (set $NYXID_PASSWORD first; user must run, not the agent)
nyxid login --base-url  --password --password-env NYXID_PASSWORD

# Verify
nyxid whoami
nyxid status                                              # shows base URL + auth state

# Refresh — usually automatic. Force one with:
nyxid auth refresh

# Log out
nyxid logout

To switch environments, log out, then log in again with a different --base-url. The CLI supports only one active base URL at a time.

1.2 Discover your identity

Three orthogonal calls. Run all three when you're new in a session and

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ChronoAIProject
• Source: ChronoAIProject/Ornn
• License: Apache-2.0
• Homepage: https://ornn.chrono-ai.fun

Install and usage instructions live in the source repository linked above.