# NodeOS Agent Starter Kit Alt du skal bruge for at koble et projekt (og dets AI-agent — KIRO, Cursor, Claude Code, Codex) på NodeOS Udviklingsplatform. Hent filerne på . --- ## Krav (læs først) - **Node.js 18+** — clienten bruger global `fetch`, ingen dependencies. - **Clienten er et ES-modul** (`import` / `export` / `import.meta.url`). Kør den enten som `nodeos-client.mjs` (anbefalet — `.mjs` kører altid som ESM), eller som `nodeos-client.js` i et projekt hvor `package.json` indeholder: ```json { "type": "module" } ``` Uden en af delene fejler den med: ``` SyntaxError: Cannot use import statement outside a module ``` --- ## Quick start 1. **Kopiér clienten** til dit projekt: ```bash mkdir -p scripts curl -o scripts/nodeos-client.mjs https://nodeos.dk/docs/agent-kit/nodeos-client.mjs ``` (Brug `nodeos-client.js` i stedet, hvis din `package.json` har `"type": "module"`.) 2. **Opret `.env`** i projektets rod (clienten læser den selv — ingen dotenv): ``` NODEOS_API_KEY=nw_live_ NODEOS_API_BASE_URL=https://nodeos.dk ``` API-nøglen hentes i portalen under **Indstillinger → API & integrationer**. Nøglen er scoped til én organisation — brug en ny nøgle per projekt. **Commit aldrig nøglen.** Tilføj `.env` til `.gitignore`. > ⚠️ Brug apex-domænet `https://nodeos.dk` — **ikke** `www.nodeos.dk`. > `www.` laver et 302-redirect, og de fleste HTTP-klienter stripper > `Authorization`-headeren på cross-host redirects (RFC 9110). Dine kald > ville da ankomme uautentificerede. 3. **Verificér forbindelsen:** ```bash node scripts/nodeos-client.mjs health # ingen auth node scripts/nodeos-client.mjs me # introspicerer din nøgle ``` 4. **Kopiér steering-skabelonen** ind i din agents regelmappe (fx `.kiro/steering/nodeos-development-platform.md`, `.cursor/rules/`, eller `AGENTS.md`) og gennemgå alle ``-markeringer. ```bash curl -o .kiro/steering/nodeos-development-platform.md \ https://nodeos.dk/docs/agent-kit/steering-template.md ``` --- ## Filer i kittet | Fil | Formål | | ---------------------------------------- | ---------------------------------------------------------------- | | `nodeos-client.mjs` / `nodeos-client.js` | Standalone CLI + ESM-modul. Samme indhold, to filendelser. | | `steering-template.md` | Generisk workflow-regelsæt til AI-agenter. Tilpas pladsholderne. | | `.env.example` | Environment-template. | | `README.md` | Denne fil. | | `API.md` | Fuld API-reference (samme indhold som `/api/public/v1/docs`). | --- ## Det aktuelle NodeOS-arbejdsloop Alt i kittet er bygget op om dette loop. Spring ikke trin over — et trin, der udelades, efterlader et hul i leveringsrecorden, ikke bare i logfilen. ```text 1. me → identitet, aktørklasse og scopes 2. doc-sources / doc-reviews → er dokumentationen frisk? venter der et review? 3. tasks / task → læs den aktuelle udviklingskontekst 4. memory → søg historik, når fortiden kan påvirke beslutningen 5. create / update → opret eller opdatér sagen 6. session-start → start en arbejdssession FØR implementering 7. event → registrér meningsfulde work events undervejs 8. session-complete → afslut eksplicit med summary + outcome 9. evidence-add → indsend leveringsevidens 10. evidence-get / evidence-supersede → læs egen evidens tilbage, erstat ved behov 11. (menneske verificerer evidensen — en agent kan aldrig selv gøre det) 12. status → Released → Released = leveret 13. doc-review-assess → behandl dokumentationsreview, når kontrakten ændrer sig ``` Kanonisk beskrivelse af pligterne: [AGENT_CONTRACT.md](./AGENT_CONTRACT.md). --- ## Scopes (runtime-sandhed) Nøglen får kun det, den skal bruge. Fire scopes er **eksplicitte** og gives aldrig implicit — heller ikke af `admin.full`: | Scope | Bruges til | | ---------------------------------------------- | ----------------------------------------------------- | | `tasks.read` / `tasks.create` / `tasks.update` | Sager | | `comments.read` / `comments.create` | Kommentarer | | `status.update` | Statusskift | | `work.read` / `work.write` | Work Sessions og work events | | `evidence.read` / `evidence.write` | Leveringsevidens, delivery, integrity | | `evidence.verify` | **Kun mennesker.** Gives aldrig til en agentnøgle | | `memory.read` | Development Memory (eksplicit) | | `docs.read` / `docs.sync` | Dokumentationskilder, releases og reviews (eksplicit) | Ikke-arvelighed, som den håndhæves i runtime: - `admin.full` medfører **ikke** `memory.read`. - `memory.read` medfører **ikke** `docs.read`. - `admin.full` medfører **ikke** `evidence.verify`, `docs.read` eller `docs.sync`. `docs.*`-endpoints kræver desuden en nøgle bundet til en aktiv agent-integration; ellers svarer API'et `409 agent_integration_required`. --- ## Brug som CLI ```bash node scripts/nodeos-client.mjs health node scripts/nodeos-client.mjs me node scripts/nodeos-client.mjs projects node scripts/nodeos-client.mjs tasks --status "Under udvikling" node scripts/nodeos-client.mjs task node scripts/nodeos-client.mjs search "dommer" --search-field title --exact node scripts/nodeos-client.mjs create --title "..." --type bug --priority high \ --area "Flutter App" --parent node scripts/nodeos-client.mjs bulk-create --file tasks.json --area "Flutter App" # (batch-create er et alias for bulk-create) node scripts/nodeos-client.mjs relations --direction all node scripts/nodeos-client.mjs update --status in_progress node scripts/nodeos-client.mjs comment "tekst" node scripts/nodeos-client.mjs completion node scripts/nodeos-client.mjs dashboard --status Released --limit 30 # Work Sessions node scripts/nodeos-client.mjs session-start "Implementér OAuth-callback" node scripts/nodeos-client.mjs event implementation_step --message "…" node scripts/nodeos-client.mjs session-wait human node scripts/nodeos-client.mjs session-resume node scripts/nodeos-client.mjs session-complete \ --summary "…" --outcome success # Delivery Evidence node scripts/nodeos-client.mjs evidence-add --type commit \ --title "fix: OAuth callback" --url https://… --session node scripts/nodeos-client.mjs evidence node scripts/nodeos-client.mjs evidence-get node scripts/nodeos-client.mjs evidence-supersede node scripts/nodeos-client.mjs delivery node scripts/nodeos-client.mjs integrity # Development Memory node scripts/nodeos-client.mjs memory "tenant isolation api keys" # Dokumentationslivscyklus node scripts/nodeos-client.mjs doc-sources node scripts/nodeos-client.mjs doc-reviews node scripts/nodeos-client.mjs doc-review-assess \ --summary "Læst og anvendt" --action "applied:Opdaterede steering-filen" node scripts/nodeos-client.mjs close --comment "Implementeret" ``` Kør uden argumenter for den fulde kommandoliste. > `link` / `links` / `unlink` er **deprecated** (sunset 2026-12-31). Brug > `evidence-add` i stedet — links spejles kun som svag, uverificerbar evidens. ### Bulk-oprettelse `bulk-create` opretter hele hierarkier i ét kald. `ref` / `parent_ref` binder opgaverne sammen uden ekstra `relate`-kald: ```json { "tasks": [ { "ref": "epic", "title": "Fase 0 — Signing", "type": "feature" }, { "ref": "sub1", "title": "Generér signing key", "parent_ref": "epic" }, { "ref": "sub2", "title": "Konfigurér CI-secrets", "parent_ref": "epic" } ], "relations": [{ "source_ref": "sub1", "target_ref": "sub2", "relation_type": "blocks" }] } ``` Kommandoen hedder `bulk-create`, med `batch-create` som alias — programmatisk hedder funktionerne `bulkCreateTasks` / `batchCreateTasks` (parallelt til `batchUpdateTasks`). Max 50 opgaver og 100 relationer per kald. Svaret er altid `200` — tjek `meta.batch` og hver enkelt `results[].status`. ### Exit codes Clienten skriver kun JSON på **stdout** og bruger stderr til reelle fejl. Exit code er `0` ved succes og `1` ved fejl — den kalder ikke `process.exit()` midt i et output, så pipes i PowerShell afsluttes rent. ## Brug programmatisk ```js import { listTasks, createTask, updateTask, addComment, batchUpdateTasks, batchCreateTasks, } from "./scripts/nodeos-client.mjs"; const tasks = await listTasks({ status: "Under udvikling" }); ``` --- ## Din agent er en NodeOS-deltager — ikke bare en API-nøgle En agent, der arbejder mod NodeOS, har en **stabil identitet**: - **Agent-integration** — den registrerede agent (navn, runtime, model). Alt arbejde, evidens og dokumentationsreview bindes til denne identitet. - **API-nøglebinding** — nøglen er bundet til én agent-integration og én organisation. Den kan ikke se en anden kundes data. - **Aktørklasse** — bestemmer hvad du må **se** (intern vs. kundevendt). Scopes bestemmer hvad du må **gøre**. De to er uafhængige. - **Revokérbar** — en nøgle kan tilbagekaldes i portalen uden at slette historikken. Det, agenten allerede har leveret, forbliver sporbart. - **Least privilege** — bed kun om de scopes, arbejdet kræver. Derfor gælder også: registrér evidens under din egen identitet, del aldrig en nøgle mellem agenter, og hardcode aldrig en nøgle i et repo. --- ## Development Memory **Hvad det er:** historiske NodeOS-udviklingsrecords — sager, beslutninger, kommentarer, leveringsbeviser og arbejdssessioner — som kan søges og følges tilbage til deres kanoniske kilde. **Hvornår du bruger den:** - før en arkitektonisk beslutning - før du ændrer rettigheder, tenant-isolation eller datasynlighed - når et problem lyder bekendt - før du genopfinder et mønster, NodeOS måske allerede har - når historisk begrundelse kan påvirke den aktuelle implementering **Hvordan:** `GET /api/public/v1/memory/search?q=…` (scope `memory.read`), CLI `memory ""`, eller MCP-værktøjet `search_development_memory`. **Hvad det ikke er:** ikke modeltræning, ikke semantisk/vektor-hukommelse, ikke autonom læring, og ikke en erstatning for aktuel dokumentation. > Dokumentation fortæller dig, hvordan systemet **skal** fungere nu. > Development Memory fortæller dig, hvordan og hvorfor tidligere arbejde skete. > Når de er uenige, **vinder den aktuelle autoritative dokumentation**. Søgningen er deterministisk full-text — prøv både dansk og engelsk formulering af det centrale begreb. Behandl resultaterne som evidens, ikke som svar: citér `source_type` + `canonical_path` i din session eller evidens. --- ## MCP — værktøjsopdagelse uden HTTP NodeOS eksponerer også en MCP-server på `https://nodeos.dk/mcp` (OAuth 2.1 — klienten logger ind som en NodeOS-bruger, og adgangen følger brugerens RLS). Brug den fra ChatGPT, Claude, Cursor eller Codex, når agenten kører som en person frem for som en integration med API-nøgle. Værktøjer: `me`, `list_areas`, `list_tasks`, `get_task`, `create_task`, `add_comment`, `search_development_memory`. Tommelfingerregel: **MCP** når et menneske er logget ind i klienten; **API-nøgle + Starter Kit** når agenten kører selvstændigt i et repo eller en pipeline (det er den eneste vej til Work Sessions og Delivery Evidence i dag). --- ## Kanoniske kilder | Emne | Kanonisk kilde | | ------------------------------------ | -------------------------------------------------------- | | API-kontrakt | `docs/API.md` + `public/openapi.yaml` | | Agentens driftskontrakt | `docs/agent-kit/AGENT_CONTRACT.md` | | Autentificering / identitet / scopes | `docs/API.md` §Auth + denne fil | | Development Memory | `docs/NODEOS_DEVELOPMENT_MEMORY.md` | | Work Sessions | `docs/WORK_SESSIONS.md` | | Delivery Evidence | `docs/DELIVERY_EVIDENCE.md` | | Leveringssikkerhed / confidence | `docs/DELIVERY_INTEGRITY.md` | | Dokumentationslivscyklus | `docs/DOCUMENTATION_SYNC.md` | | MCP | `src/lib/mcp/` + `/.well-known/oauth-protected-resource` | | Starter Kit | denne fil | Andre dokumenter må opsummere disse — aldrig duplikere dem. --- ## Reference - **Human-readable API-docs:** - **Markdown (for AI-agenter uden JS):** - **OpenAPI-spec:** - **Healthcheck (uden auth):**