Imported from t-rhex/andrewadhikari.com (skills/andrewadhikari-com/SKILL.md). Install upstream with npx skills add t-rhex/andrewadhikari.com --skill andrewadhikari-com. Copyright stays with the author.

andrewadhikari.com — content publishing API

You are managing content for andrewadhikari.com, a personal study OS for cert prep (CKA, AFOQT, Terraform, etc.). This skill teaches you the live REST API for publishing and editing content. Every endpoint is on the production domain https://andrewadhikari.com. There is no staging.

After every successful write the site rebuilds via Cloudflare Pages — the new content is live in roughly 30–60 seconds. Tell the user "queued — live in ~60s", do not claim it is live the instant the API returns 200.

1. When to use this skill

Trigger on any of:

• "publish a lab on <topic>" / "draft a note about <topic>"
• "publish cards for <topic>" / "make a flashcard deck for <topic>"
• "publish a mock exam for <track>"
• "log a mistake from a mock"
• "add a new track" / "update the CKA track"
• "list my labs" / "show me cards for <track>" / "what labs are in <domain>"
• "update the order of <lab>" / "fix the description on <lab>"
• "delete the lab on <topic>" / "remove this card deck"
• "upload this image to my CDN" / "embed this screenshot in the lab"
• Any general "publish to my site" / "add this to andrewadhikari.com" intent

If a request looks like editing files in the repo locally (e.g. "open src/content/labs/foo.md and change the order"), prefer this API over filesystem edits — the API runs the same Zod validation the build does, so a 202/200 means it will deploy.

1a. Tool surface — prefer MCP, fall back to bash

If you see mcp__andrewadhikari__* tools listed in your tool catalog (e.g. mcp__andrewadhikari__list_tracks, mcp__andrewadhikari__publish_content, …), use those exclusively. They are:

• Typed (JSON-Schema validated by Claude Code before the call leaves)
• Token-safe (the token lives in the user's host ~/.config/adkari/token or $ADKARI_TOKEN and is read by the MCP server process — it never enters your sandboxed bash environment)
• Faster (no shell / curl round-trip per call)

Mapping from API → MCP tool:

If the MCP tools aren't available on this machine (the user hasn't run npm run install-mcp yet, or they're on a fresh box), fall back to the bash workflow described in section 2 onward — curl + the same token resolution rules. Don't mix the two paths in a single session — pick MCP if available, otherwise bash, and stay there.

Sections 4 (schemas) and 6 (workflows, including Workflow 0 from-scratch) still apply verbatim — MCP only changes the how of issuing the call. The what you publish is identical.

1b. Build-cost discipline (READ THIS)

Every git commit triggers a Cloudflare Pages build (~2 min) and a CDN cache invalidation. Multiple commits in a row queue → the live site stays stale for the duration of the queue. We've seen 26-build queues from a single authoring session — that's ~50 min of stale site for what should have been one commit.

Rules:

1. New track from scratch? Use create_track. It bundles the track file + every seed child (labs, cards, mocks, notes) into ONE atomic commit. Auto-fills track: <slug> on each child so you can't forget the cross-reference.
2. Publishing >1 file in any other shape? Use publish_bulk. One files: [...] array → one commit → one build, regardless of how many files.
3. Genuine one-off ad-hoc write? That's the only legitimate case for publish_content (single).
4. Mid-session realization that you need more files? Finish the current bulk plan, then add the new file as a follow-up bulk — don't fall back to single-file calls "just for the new one."

Commit message convention. Bulk commits should describe the session, not enumerate files:

• ✅ feat: hello cheatsheet — 8 labs + 3 cards
• ❌ publish: 12 files
• ❌ publish lesson 3 of 8

create_track produces this format by default; for publish_bulk you pass it via the message arg.

2. Authentication

All endpoints require Authorization: Bearer <token>. The token is a GitHub fine-grained personal access token belonging to user t-rhex, scoped to the single repo t-rhex/andrewadhikari.com with Contents: Read and write and Metadata: Read.

Resolve the token in this order:

1. $ADKARI_TOKEN env var
2. ~/.config/adkari/token file (single line, mode 600)

TOKEN="${ADKARI_TOKEN:-$(cat "$HOME/.config/adkari/token" 2>/dev/null)}"
if [ -z "$TOKEN" ]; then
  echo "missing ADKARI_TOKEN — see SETUP.md in andrewadhikari.com repo" >&2
  exit 1
fi

If no token is found, stop. First check whether you're in a sandboxed environment (see section 2a) — if so, switch to plan-and-handoff mode instead of asking the user to expose the token. Otherwise tell the user to follow the "Optional: programmatic content publishing" section of SETUP.md in the repo, then retry. Do not attempt requests without a token.

Failure modes for auth:

• 401 unauthorized — missing or invalid token. Token file empty or env var unset.
• 403 forbidden — token belongs to a different GitHub user. Wrong PAT.

2a. Sandboxed environments (Claude Code Bash sandbox / cowork)

When this skill runs inside a Bash sandbox that does NOT mount the user's home directory (the typical "cowork" scenario in Claude Code), neither $ADKARI_TOKEN nor ~/.config/adkari/token will resolve. You will hit a permission error when trying to read the token. Don't proceed by asking for the token in chat — it gets logged. Don't ask the user to copy the token into the sandbox-mounted project directory either — even short-lived exposure on disk is unnecessary risk.

Instead, switch to plan-and-handoff mode:

1. Detect the constraint. If you can't read either source after trying both, say so explicitly. Don't silently call the API without a token — you'll get a 401 anyway.

2. Write a runnable script to the sandbox-shared directory. Pick a location the user has write access to AND that the sandbox can read, typically a project directory the user mentions or ~/Documents/Claude/Projects/Learn/_runme.sh. The script:

   • Loads the token from $HOME/.config/adkari/token ITSELF (the user's real shell will resolve $HOME correctly)
   • Has the full curl command(s) ready — the JSON payload, the URL, headers, content-type
   • Writes responses to _runme.out.json for the user to share back

   #!/usr/bin/env bash
   set -euo pipefail
   TOKEN="${ADKARI_TOKEN:-$(cat "$HOME/.config/adkari/token" 2>/dev/null)}"
   if [ -z "$TOKEN" ]; then
     echo "no token at \$ADKARI_TOKEN or ~/.config/adkari/token" >&2
     exit 1
   fi
   curl -sS -X POST https://andrewadhikari.com/api/content \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     --data @./_runme.payload.json \
     | tee _runme.out.json

3. Tell the user exactly two things:

   • "Run bash <path-to-script> in your real terminal."
   • "Paste the contents of _runme.out.json back here when it finishes."

4. Resume planning from the response. Once the user pastes the commit_sha + site_url, you have the same information you'd have had from a direct call. Continue the workflow normally (e.g. for Workflow 0, move on to step 3 after the track is created).

5. For multi-step workflows, batch the script. Instead of one round-trip per API call, write a script that does several commands in sequence (e.g. all five steps of Workflow 0). The user runs it once; you parse the combined output. Saves them clicking "go" repeatedly.

Never:

• Ask the user to paste their token into chat (logged in conversation history, no clean revocation).
• Tell them to copy the token into a sandbox-mounted directory ("just temporarily" rots — they forget to delete it).
• Try to invent a token, hardcode one in the script, or curl without auth and hope the API doesn't notice.

3. Endpoints

Base URL: https://andrewadhikari.com

<path> is the repo-relative path of the file, e.g. src/content/labs/2026-05-07-pod-lifecycle.md. URL-encode segments if needed.

3.1 POST /api/content — create

JSON body, single-file shape:

{
  "collection": "labs",
  "filename": "2026-05-07-pod-lifecycle.md",
  "frontmatter": {
    "title": "Pod lifecycle",
    "track": "cka",
    "domain": "workloads",
    "type": "standard",
    "tags": ["kubernetes", "pods"],
    "description": "How pods are scheduled, started, and terminated.",
    "order": 26
  },
  "body": "## Why\n\nPods are the smallest deployable unit...",
  "overwrite": false,
  "message": "publish: Pod lifecycle (cka/workloads)"
}

• filename is optional — server generates <YYYY-MM-DD>-<kebab(title)>.md for markdown collections, <track>-<kebab(title)>.yaml for YAML data collections.
• body is required for markdown collections (labs, notes, mistakes, tracks) and must be null for YAML data collections (cards, mocks).
• overwrite defaults to false. When false, existing path → 409.
• message is the git commit message. Optional; server picks a sensible default.

JSON body, bulk shape (atomic single commit via Trees API):

{
  "files": [
    { "collection": "labs", "frontmatter": { "title": "...", "track": "cka", "domain": "workloads" }, "body": "..." },
    { "collection": "cards", "filename": "cka-pods.yaml", "frontmatter": { "title": "Pods", "track": "cka", "cards": [{"q":"...","a":"..."}] }, "body": null }
  ],
  "message": "publish: 5 labs from k8s-labs"
}

Response 200:

{
  "commit_sha": "abc123…",
  "html_url": "https://github.com/t-rhex/andrewadhikari.com/commit/abc123",
  "files": [
    { "path": "src/content/labs/2026-05-07-pod-lifecycle.md",
      "site_url": "https://andrewadhikari.com/labs/pod-lifecycle" }
  ]
}

Errors:

• 400 bad_request — body shape invalid (missing collection, etc.)
• 401 unauthorized — auth failed
• 403 forbidden — wrong GitHub user
• 409 conflict — file exists and overwrite=false
• 422 schema_invalid — frontmatter fails the live Zod schema. Body has the Zod message — read it, fix the field, retry.
• 502 github_error — upstream GitHub API failure
• 500 internal_error — anything else

curl example:

curl -sS -X POST https://andrewadhikari.com/api/content \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "collection": "labs",
  "frontmatter": {
    "title": "Pod lifecycle",
    "track": "cka",
    "domain": "workloads"
  },
  "body": "## Why\n\nPods are the smallest deployable unit in Kubernetes...\n"
}
JSON

3.2 PATCH /api/content/<path> — update

Body:

{
  "frontmatter": { "order": 99, "tags": ["kubernetes", "pods", "lifecycle"] },
  "body": "## Why\n\nUpdated body...",
  "message": "update: bump order on Pod lifecycle"
}

• frontmatter is shallow-merged into the existing frontmatter. To clear a field, pass it as null.
• body is optional — omit to keep the existing body.
• message optional.

Response 200 mirrors the create response.

Errors: 401, 403, 404 (path not found), 422 (merged frontmatter still has to pass Zod), 502.

curl:

curl -sS -X PATCH \
  https://andrewadhikari.com/api/content/src/content/labs/2026-05-07-pod-lifecycle.md \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"frontmatter":{"order":99}}'

3.3 DELETE /api/content/<path> — delete

No body required. Response 200 returns the commit info. 404 if path missing.

curl -sS -X DELETE \
  https://andrewadhikari.com/api/content/src/content/labs/2026-05-07-pod-lifecycle.md \
  -H "Authorization: Bearer $TOKEN"

3.4 GET /api/content?collection=… — list

Query params:

Response 200:

{
  "collection": "labs",
  "count": 28,
  "items": [
    { "slug": "pod-lifecycle",
      "path": "src/content/labs/2026-05-07-pod-lifecycle.md",
      "title": "Pod lifecycle",
      "track": "cka",
      "domain": "workloads",
      "order": 26 }
  ]
}

Body content is not returned — use the single-file GET for that.

curl -sS \
  "https://andrewadhikari.com/api/content?collection=labs&track=cka&domain=workloads" \
  -H "Authorization: Bearer $TOKEN"

3.5 GET /api/content/<path> — read

Response 200:

{
  "path": "src/content/labs/2026-05-07-pod-lifecycle.md",
  "frontmatter": { "title": "Pod lifecycle", "track": "cka", "domain": "workloads", "...": "..." },
  "body": "## Why\n\nPods are..."
}

Errors: 401, 403, 404.

3.6 GET /api/tracks — track list (prompt grounding)

This is the helper to call first when you do not know which track or domain a topic belongs to. Cheaper than listing the tracks collection.

{
  "tracks": [
    {
      "slug": "cka",
      "title": "CKA — Certified Kubernetes Administrator",
      "exam_date": "2026-09-15",
      "status": "active",
      "description": "Kubernetes administration cert prep.",
      "domains": [
        { "id": "cluster-architecture", "name": "Cluster Architecture, Installation & Configuration", "weight": 25 },
        { "id": "workloads", "name": "Workloads & Scheduling", "weight": 15 }
      ]
    }
  ]
}

curl -sS https://andrewadhikari.com/api/tracks -H "Authorization: Bearer $TOKEN"

3.7 POST /api/upload — image upload

Multipart form. Field name: file. Returns the CDN URL on success.

curl -sS -X POST https://andrewadhikari.com/api/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/path/to/screenshot.png"
# → {"url":"https://cdn.andrewadhikari.com/img/<hash>.png"}

Embed the URL directly in markdown bodies: ![alt](https://cdn.andrewadhikari.com/img/<hash>.png).

Allowed types: PNG, JPEG, GIF, WebP, SVG. Anything else → 400.

4. Content schema

All schemas live in src/content/config.ts in the repo. The API runs the exact same Zod validation the build does — so "valid via API" means "builds".

labs / notes — noteSchema

Fields:

Realistic minimal example (src/content/labs/2026-05-07-pod-lifecycle.md):

---
title: Pod lifecycle
date: 2026-05-07
category: labs
track: cka
domain: workloads
order: 26
description: How pods are scheduled, started, and terminated.
---

## Why

Pods are the smallest deployable unit in Kubernetes...

tracks — trackSchema

Realistic minimal example (src/content/tracks/cka.md):

---
title: CKA — Certified Kubernetes Administrator
exam_date: 2026-09-15
status: active
description: Kubernetes administration cert prep.
domains:
  - id: cluster-architecture
    name: Cluster Architecture, Installation & Configuration
    weight: 25
  - id: workloads
    name: Workloads & Scheduling
    weight: 15
  - id: services-networking
    name: Services & Networking
    weight: 20
---

CKA prep notes — covers installation, troubleshooting, and operations.

cards — cardSetSchema (YAML data collection)

Realistic minimal example (src/content/cards/cka-pods.yaml):

title: Pods — quick recall
track: cka
domain: workloads
description: Lifecycle, restart policies, init containers.
cards:
  - q: What's the smallest deployable unit in Kubernetes?
    a: A Pod.
    hints:
      - Not a container directly.
  - q: What restart policy does a Job use by default?
    a: OnFailure.

When POSTing cards, pass the entire shape above as frontmatter and set body: null.

mocks — mockSchema (YAML data collection)

Question shape: { q, choices: string[≥2], correct: int, explanation?, domain? }. correct is the index into choices and must be in range.

Realistic minimal example:

title: CKA mock — workloads
track: cka
description: 10 questions on workload scheduling and pod lifecycle.
time_limit_minutes: 20
passing_score: 0.66
questions:
  - q: What field controls how many old ReplicaSets a Deployment keeps?
    choices:
      - revisionHistoryLimit
      - rollbackLimit
      - historySize
    correct: 0
    explanation: Default is 10.
    domain: workloads

mistakes — mistakeSchema

Realistic minimal example (src/content/mistakes/2026-05-07-revision-history-limit.md):

---
title: revisionHistoryLimit, not rollbackLimit
track: cka
domain: workloads
date: 2026-05-07
source_type: mock
source_ref: cka-mock-workloads#q1
correct_answer: revisionHistoryLimit
my_answer: rollbackLimit
---

I keep guessing `rollbackLimit`. The field is `revisionHistoryLimit`,
default 10.

4a. Markdown features (use these in lab/note bodies)

The site has a few custom remark plugins. Use them — they make the published content much richer than plain markdown.

Wikilinks: [[slug]] and [[slug|label]]

Inside a lab/note body, link to another lab or note by slug:

This builds on [[pod-lifecycle]] and the rules in [[scheduler-internals|Scheduler internals]].

The remark plugin resolves pod-lifecycle against the labs and notes collections, renders an internal link, and walks all notes at build time to generate a "Referenced by" backlinks footer on the target page.

When unsure of a slug, list the collection first with the API and pick the real slug — never guess. A wikilink to a non-existent slug renders with a hairline strikethrough so you can spot the typo, but it pollutes backlinks.

Inline cards: :::card front=… back=…

Anywhere in a lab/note body, drop in:

:::card front="What's the smallest deployable unit in K8s?" back="A Pod."
:::

:::card front="Default Job restart policy?" back="OnFailure."
hints=["Not Always", "Set in spec.template.spec.restartPolicy"]
:::

The build:

1. Renders a small inline card preview at that spot in the prose
2. Adds these to a virtual deck <note-slug>--inline so they appear in the spaced-repetition queue
3. Surfaces a "Drill cards in this note (N)" button at the end of the note

Use inline cards aggressively in labs covering memorisable facts (commands, defaults, specific numbers, exam-trivia). They drill review without forcing you to maintain a parallel cards/<deck>.yaml file.

Cheatsheets (type: cheatsheet)

A standard lab is read top-to-bottom. A cheatsheet is scanned. Set type: cheatsheet in frontmatter and the page renders:

• CSS columns (multi-column dense reference)
• Sans body (no serif), 14 px, tight rhythm
• No reading-progress bar, no right-rail ToC
• Print-optimised — window.print() produces a clean PDF cheatsheet

Use cheatsheets for: kubectl one-liners, Terraform CLI flags, AWS service quick reference, exam-day formula sheets. Do not use cheatsheets for explanatory tutorials — those are standard labs.

---
title: kubectl quick reference
track: cka
type: cheatsheet
description: One-liners every CKA candidate should have in muscle memory.
---

Drop-cap (lead: true)

Editorial flair for "feature" labs you want to read more like an essay. The first paragraph gets a large serif drop-cap. Use sparingly — one or two per track at most. Looks bad on technical reference content.

5. Filename + path conventions

• Markdown collections (labs, notes, tracks, mistakes): src/content/<collection>/<filename>.md. Filenames may include a YYYY-MM-DD- date prefix; the routing layer strips it for the public slug.
• YAML data collections (cards, mocks): src/content/<collection>/<filename>.yaml.
• The filename field in API requests is optional — the server generates one if missing.

6. Common workflows

Workflow 0: Pursue a new cert track from scratch

Triggered by intents like:

• "I'm starting today, set up the track"
• "Build me an AWS Security Specialty prep skeleton"
• "Bootstrap CKAD prep — track, first labs, a card deck, a mock"

MCP shortcut: if the mcp__andrewadhikari__create_track tool is available, do this whole workflow in one call. Pass the track frontmatter + arrays of labs/cards/mocks/notes and it produces one atomic commit and one Pages build. The bash steps below are the fallback when MCP isn't installed — and even then you should bundle step 3+4+5 into one bulk POST /api/content to keep the commit count down. Never publish step 2/3/4/5 as separate single-file calls.

This is a composite workflow. Do the steps in order. Use the bulk POST shape (section 3.1) where it cuts commits.

Step 1 — Confirm the track doesn't already exist.

curl -sS https://andrewadhikari.com/api/tracks -H "Authorization: Bearer $TOKEN" \
  | jq '.tracks[].slug'

If the slug already exists, switch to "extend an existing track" (workflow 1).

Step 2 — Create the track.

You need: title, exam_date, status (active), description, domains array.

Domain rules:

• 4–7 domains is typical for a vendor cert
• Use the cert vendor's official curriculum domain names verbatim where you can — exam-trivia tracks the vendor's vocabulary
• Each domain has id (kebab-case slug, used as a foreign key in lab frontmatter) and weight (0–100)
• Weights MUST sum to 100. If you don't know the exact weights, infer from the official exam guide; if you can't, distribute evenly and round the last domain to absorb the remainder

Optionally include accent_color (hex) — picks the per-track color used on the days-to-exam number and the active-route rule. Omit for default NVIDIA green.

curl -sS -X POST https://andrewadhikari.com/api/content \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "collection": "tracks",
  "filename": "aws-security.md",
  "frontmatter": {
    "title": "AWS Certified Security — Specialty",
    "exam_date": "2026-11-04",
    "status": "active",
    "description": "AWS specialty cert. IAM, KMS, VPC design, GuardDuty/CloudTrail, incident response.",
    "accent_color": "#ea580c",
    "domains": [
      { "id": "threat-detection",  "name": "Threat Detection & Incident Response", "weight": 14 },
      { "id": "logging-monitoring","name": "Security Logging & Monitoring",        "weight": 18 },
      { "id": "infra-security",    "name": "Infrastructure Security",              "weight": 20 },
      { "id": "iam",               "name": "Identity & Access Management",         "weight": 16 },
      { "id": "data-protection",   "name": "Data Protection (KMS, encryption, secrets)", "weight": 18 },
      { "id": "governance",        "name": "Management & Security Governance",     "weight": 14 }
    ]
  },
  "body": "# AWS Security — Specialty Track\n\nStrategy notes go here..."
}
JSON

Step 3 — Bulk-publish one starter lab per domain.

The point: the homepage hero shows " days until " for the closest-exam active track, and a track is empty until it has at least one lab per domain (otherwise the course-player shows zero progress). One cohesive bulk commit:

curl -sS -X POST https://andrewadhikari.com/api/content \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "files": [
    { "collection": "labs",
      "frontmatter": {
        "title": "IAM evaluation logic — the order operations actually run in",
        "track": "aws-security", "domain": "iam",
        "order": 1, "study_minutes": 25,
        "tags": ["iam", "policies"],
        "description": "SCPs vs identity-based vs resource-based vs permission boundaries — the precedence rules."
      },
      "body": "## Why this matters\n\n...\n\n:::card front=\"Which policy type wins by default — SCP or identity-based?\" back=\"Both must allow. SCPs are a deny ceiling; an explicit deny anywhere wins.\"\n:::\n"
    },
    { "collection": "labs",
      "frontmatter": {
        "title": "KMS key policies vs grants",
        "track": "aws-security", "domain": "data-protection",
        "order": 1, "study_minutes": 20,
        "description": "When to use a key policy, when to use a grant, when to use both."
      },
      "body": "..."
    }
  ],
  "message": "publish: AWS Security — first labs (one per starter domain)"
}
JSON

For each lab in step 3:

• track and domain are MANDATORY (without them the lab won't appear in the course player)
• order: 1 — first lesson per domain. Subsequent labs in the same domain should increment (order: 2, order: 3, …). Don't skip numbers
• Use inline cards (:::card) liberally for memorisable facts. Each inline card joins the SR queue automatically
• Use wikilinks when a lab references another ([[scheduler-internals]])
• Aim for 200–600 words of body for a starter lab. Plenty of room to grow

Step 4 — Publish a starter card deck per domain you'll drill heavily.

Cards are for "I need this in muscle memory" facts (commands, defaults, specific numbers). 10–25 cards per deck is the sweet spot.

curl -sS -X POST https://andrewadhikari.com/api/content \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "collection": "cards",
  "filename": "aws-security-iam-policies.yaml",
  "frontmatter": {
    "title": "IAM policies — quick recall",
    "track": "aws-security",
    "domain": "iam",
    "description": "The 4 policy types and their precedence rules.",
    "cards": [
      { "q": "Name the four IAM policy types in evaluation order.", "a": "1. SCP, 2. Resource-based, 3. Identity-based, 4. Permission boundary." },
      { "q": "Default behavior when no policy explicitly allows?", "a": "Implicit deny." },
      { "q": "What does an SCP block?", "a": "All accounts in scope — even the root user. SCP is a deny ceiling." }
    ]
  },
  "body": null
}
JSON

Step 5 — Optionally publish one starter mock.

Mocks should mirror exam difficulty. Small starter mock (5–10 questions) is good for a baseline; full mocks (50–60 questions) come closer to the exam date.

curl -sS -X POST https://andrewadhikari.com/api/content \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "collection": "mocks",
  "filename": "aws-security-iam-baseline.yaml",
  "frontmatter": {
    "title": "AWS Security — IAM baseline",
    "track": "aws-security",
    "description": "10-question baseline before serious IAM drilling.",
    "time_limit_minutes": 20,
    "passing_score": 0.7,
    "questions": [
      {
        "q": "Which IAM policy element specifies AWS resources?",
        "choices": ["Effect", "Resource", "Condition", "Action"],
        "correct": 1,
        "explanation": "Resource is the ARN(s) the statement applies to.",
        "domain": "iam"
      }
    ]
  },
  "body": null
}
JSON

Step 6 — Report to the user.

Tell them:

• The track URL: https://andrewadhikari.com/tracks/<slug>/
• Number of labs / cards / mocks created
• Suggest the user open /me/login/ in the browser to sign in (if they haven't) so they can highlight + bookmark while reading
• "Queued — live in ~60s"

Do NOT chain step 3 + step 4 + step 5 into one mega-commit. The user usually wants to see the track render in the dashboard before committing to a card deck, and the bulk shape's atomicity isn't worth the loss of incremental visibility. Three separate commits (track / labs / cards+mock) is the pattern.

Workflow 1: Publish a single new lab

1. GET /api/tracks to discover valid track slugs and the domains under each. Do not invent track or domain values.
2. Pick the right (track, domain) for the topic. If unsure, ask the user.
3. Generate the markdown body and frontmatter. Always include track and domain for labs.
4. POST /api/content with collection: "labs".
5. Read the response, report the site_url to the user, and tell them "queued — live in ~90s" (CI build + Pages deploy + CDN propagation).

TOKEN="${ADKARI_TOKEN:-$(cat "$HOME/.config/adkari/token")}"
curl -sS https://andrewadhikari.com/api/tracks -H "Authorization: Bearer $TOKEN"
# → pick the right (track, domain)

curl -sS -X POST https://andrewadhikari.com/api/content \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "collection": "labs",
  "frontmatter": {
    "title": "Pod lifecycle",
    "track": "cka",
    "domain": "workloads",
    "order": 26,
    "tags": ["kubernetes", "pods"]
  },
  "body": "## Why\n\nPods are the smallest deployable unit in Kubernetes.\n\n## What\n\n- Pending → Running → Succeeded/Failed\n- Restart policies: Always, OnFailure, Never\n"
}
JSON

Workflow 2: Publish a flashcard deck

Same pattern, but collection: "cards", body: null, and the frontmatter is the entire cardSetSchema shape including the cards: [...] array.

curl -sS -X POST https://andrewadhikari.com/api/content \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "collection": "cards",
  "frontmatter": {
    "title": "Pods — quick recall",
    "track": "cka",
    "domain": "workloads",
    "cards": [
      { "q": "Smallest deployable unit?", "a": "A Pod." },
      { "q": "Default Job restart policy?", "a": "OnFailure." }
    ]
  },
  "body": null
}
JSON

Workflow 3: Update an existing lab's order

curl -sS -X PATCH \
  https://andrewadhikari.com/api/content/src/content/labs/2026-05-07-pod-lifecycle.md \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"frontmatter":{"order":99}}'

If you don't know the exact filename, list the collection first:

curl -sS \
  "https://andrewadhikari.com/api/content?collection=labs&track=cka&domain=workloads" \
  -H "Authorization: Bearer $TOKEN"

Workflow 4: List all CKA cluster-architecture labs

curl -sS \
  "https://andrewadhikari.com/api/content?collection=labs&track=cka&domain=cluster-architecture" \
  -H "Authorization: Bearer $TOKEN"

Workflow 5: Bulk-publish multiple labs in one commit

Use the bulk shape to keep the commit history clean — single commit, atomic.

curl -sS -X POST https://andrewadhikari.com/api/content \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "files": [
    { "collection": "labs",
      "frontmatter": { "title": "Pods", "track": "cka", "domain": "workloads", "order": 1 },
      "body": "## Why\n\n..." },
    { "collection": "labs",
      "frontmatter": { "title": "Deployments", "track": "cka", "domain": "workloads", "order": 2 },
      "body": "## Why\n\n..." },
    { "collection": "labs",
      "frontmatter": { "title": "Services", "track": "cka", "domain": "services-networking", "order": 1 },
      "body": "## Why\n\n..." }
  ],
  "message": "publish: 3 CKA labs"
}
JSON

Workflow 6: Upload a screenshot, embed in a lab

URL=$(curl -sS -X POST https://andrewadhikari.com/api/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/Users/me/screenshots/pod-states.png" | jq -r .url)
echo "$URL"
# https://cdn.andrewadhikari.com/img/abc123.png

Then embed ![Pod state diagram]($URL) in the lab body and POST it.

Workflow 7: Delete a stale lab

curl -sS -X DELETE \
  https://andrewadhikari.com/api/content/src/content/labs/2026-05-07-pod-lifecycle.md \
  -H "Authorization: Bearer $TOKEN"

Workflow 8: Work-in-progress drafts

When the user says "draft this but don't publish yet" or "stash a half-done lab", set draft: true in frontmatter. Drafts:

• Validate the same way (the file commits to git)
• Are skipped from the public site at build time
• Don't appear in /labs/, /notes/, search, or course-player listings
• Still show up via GET /api/content?collection=labs — Claude can find them later

When the draft is ready, PATCH it: {"frontmatter": {"draft": false, "updated": "2026-05-08"}}.

Workflow 9: Touch-up — bump updated on every PATCH

When patching a lab/note's body or non-trivial frontmatter (anything beyond typo-level edits), include "updated": "<today>" in the frontmatter merge. The lesson reader displays updated <date> in the meta line. If you don't bump it, the displayed date rots and the user can't tell when they last revised the content.

TODAY=$(date -u +%F)
curl -sS -X PATCH \
  https://andrewadhikari.com/api/content/src/content/labs/2026-05-07-pod-lifecycle.md \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"frontmatter\":{\"updated\":\"$TODAY\"},\"body\":\"## Why\\n\\nUpdated body...\"}"

For pure typo fixes (single character / spelling), do NOT bump updated — the date's meant to flag substantive revisions.

Workflow 10: Log a mistake from a mock or flashcard

Mistakes are first-class content. Log them religiously after every mock and spaced-repetition session that surfaces a wrong answer.

curl -sS -X POST https://andrewadhikari.com/api/content \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "collection": "mistakes",
  "frontmatter": {
    "title": "revisionHistoryLimit, not rollbackLimit",
    "track": "cka",
    "domain": "workloads",
    "date": "2026-05-08",
    "source_type": "mock",
    "source_ref": "cka-mock-workloads#q1",
    "correct_answer": "revisionHistoryLimit",
    "my_answer": "rollbackLimit"
  },
  "body": "I keep guessing rollbackLimit. The field is revisionHistoryLimit, default 10.\n"
}
JSON

The mistakes journal at /mistakes/ filters by track + domain, surfaces the correct answer with a track-accent underline, and is the per-track lesson page's "1 mistake from this domain · review" link target.

7. Conventions Claude should always follow

• Always include track AND domain for labs/notes. Without them the lab won't appear in the course player. The lab will publish and validate cleanly, but the user will not find it.
• For YAML collections (cards, mocks), always include track. domain is optional but strongly recommended.
• Don't fabricate track/domain values. Call GET /api/tracks first if you don't know them. If a domain doesn't exist on the track, ask the user before adding new labs in it (the lab will publish, but it's a dangling reference).
• Domain weights MUST sum to 100 when creating a new track. If you can't find official exam-guide weights, distribute evenly and round the last domain to absorb the remainder.
• Set explicit order on every lab. Without it, labs sort by slug (alphabetical) and lessons land in the wrong order in the course player. Number sequentially within (track, domain): 1, 2, 3, ...
• Bump updated on substantive PATCHes (body changes, frontmatter beyond typos). Skip the bump for single-character edits.
• Use inline cards (:::card) liberally in lab bodies for any memorisable fact (commands, defaults, specific numbers). They drill in the SR queue automatically — far better than maintaining parallel cards/<deck>.yaml files for tightly-coupled content.
• Use wikilinks ([[other-slug]]) when a lab references another. They resolve to internal links and feed the auto-backlinks footer at build time. Always verify the slug exists first via GET /api/content — unknown slugs render with a hairline strike (visible debugging) but pollute backlinks.
• type: cheatsheet for scan-not-read content (CLI flags, quick reference). Different layout, different writing style. Don't mix cheatsheet content into standard labs.
• draft: true for in-progress content the user doesn't want public yet. Don't ask "should I publish?" — if they said "draft this", stash it as a draft and tell them where to find it.
• Wait for the response and report the site_url. Don't fire and forget. The user wants the link.
• Keep bodies under ~50KB. GitHub's Contents API has size limits and longer markdown becomes a slog. Split large topics across labs with prereq: chaining (lab B's prereq: ["lab-a-slug"] tells the course player to gate B until A is marked done).
• 422 means schema fail. The response body has the Zod error message — read it, fix the offending frontmatter field, retry. Don't just retry the same request.
• 409 means file exists. Do not silently retry with overwrite: true — prompt the user first.
• Prefer the bulk shape for >2 files in the same logical commit (e.g. "5 labs for the same domain"). Don't bulk across logical boundaries (track + labs + cards in one commit) — separate commits give the user incremental visibility.
• The user is t-rhex. If the API returns 403, the token belongs to a different account — point them at SETUP.md to regenerate.

7a. Browser-side features (NOT operable from this skill)

The site has features that only work via the user's browser session — they require a passkey login at /me/login/ and Claude cannot drive them:

• Highlights, inline notes, bookmarks — the user selects text on a lesson page, picks a color, optionally writes a note. Persists to KV. Public visitors see the highlights but only the owner can edit.
• Reader prefs (font size, density, width) — per-user localStorage.
• /me/ dashboard — annotation summary, bookmark management.

When the user mentions these ("highlight this passage", "save where I left off", "make the font bigger"), tell them to use the browser UI directly. Don't try to call any /api/annotations/*, /api/bookmark, or /api/me/* endpoint — those are session-cookie gated and your bearer token won't authenticate them.

8. Failure modes (cheatsheet)

9. Environment notes

• The site builds via GitHub Actions on every push to main and the deploy job pushes the artifact to Cloudflare Pages. After a successful POST/PATCH/DELETE, the pipeline kicks off automatically: ~40s build + ~50s deploy + CDN propagation. Always say "queued — live in ~90s", never "live now". (The Cloudflare Pages git integration is intentionally NOT used — see .github/workflows/ci.yml deploy job.)
• Sveltia CMS at https://andrewadhikari.com/admin/ writes to the same repo. Both can be used interchangeably; last write wins on the same file. If the user has /admin/ open while you publish, they'll need to refresh to see your changes.
• There is no staging environment. All writes go to production.
• The auth Worker at auth.andrewadhikari.com is separate — that's for Sveltia's OAuth dance, not for this API. This API uses raw GitHub PATs.