How products are authored

Most engineers should build Nexus products by writing validated files, not by editing framework internals.

The authoring model is intentionally narrow. Fresh graduates and most engineers should express product intent through files. Staff engineers and platform owners maintain the runtime internals.

The authored files

File	What it declares
`NEXUS.md`	Pack identity, purpose, outputs, and high-level rules
`AGENTS.md`	Agents, their roles, model ids, tools, and structured output schemas
`SKILLS.md`	Reusable instruction fragments and constraints
`TEAMS.md`	Reusable multi-agent teams, coordination rules, and artifact output contracts
`WORKFLOWS.md`	Ordered or conditional flows across validated agents, teams, or workflows
`TOOLS.md`	Requested capability access through Pinax
`EVALS.md`	Eval fixtures, thresholds, and required checks

What all us should do

Describe the product and its bounded job.
Choose from approved model ids.
Request governed capabilities through TOOLS.md.
Define structured outputs.
Add eval fixtures and expectations.

What all of should not do

Write workflow-local Python hooks.
Call LiteLLM directly.
Decide auth or token strategy inside the pack.
Construct source URLs, artifact ids, or lineage links in model text.
Create raw shell tools by default.
Treat tool declarations as self-approved access grants.

Why the pack is strict

The pack grammar is constrained so product definitions remain reviewable, validated, and distinct from runtime implementation code.

Database-backed authored definitions

Nexus also supports database-backed authored definitions for clinicians and platform template flows.

Source	Who uses it	Storage	Runtime path
File-authored pack	Engineers	Version-controlled files	Loaded directly by `n1r.core`
Database-authored definition	Platform, clinic, or clinician owners	DocumentDB	Normalized by `n1r.core` into the same runtime model
Clinicians should not edit framework internals. They should edit only the constrained authoring surface for their own agents.