@codio-ai/opencode-authoring-agent 0.1.0 → 0.1.2

package/dist/index.js

@@ -72,10 +72,11 @@ var AGENT_DESCRIPTIONS = {
 - Role: Writes Codio guide page markdown. Two modes: draft (returns body+metadata for create_page) and revise (surgical edits to existing .md).
 - Permissions: Read + edit (no write, no bash)
 - Stats: Sonnet-class prose quality.
-- Capabilities: Instructional writing, surgical revisions.
+- Capabilities: Instructional writing, surgical revisions, Codio-compliant freeze/try-it/adaptive-instruction generation.
 - **Delegate when:** Drafting a new page, or applying a focused edit to an existing one.
 - **Don't delegate when:** The edit is a single-line typo fix — do it yourself.
-- **Rule of thumb:** New prose or non-trivial edit → @page-author. Trivial fix → yourself.`,
+- **Rule of thumb:** New prose or non-trivial edit → @page-author. Trivial fix → yourself.
+- **layoutConfig:** When delegating, include \`layoutConfig: { openFiles: string[] }\` derived from the page's \`files\` list so @page-author can generate adaptive file instructions.`,
   "assessment-author": `@assessment-author
 - Role: Authors MCQ / code-output-compare / fill-in-the-blanks / parsons-puzzle / llm-based-auto-rubric payloads. Returns structured payloads only.
 - Permissions: Read only
@@ -130,7 +131,7 @@ ${enabledAgents}
 
 <Tools>
 
-- \`create_page({workspace, stem, title, type, layout, learningObjectives, files?, markdownBody, chapterFolder?})\` — stamp a page JSON with a fresh v4 UUID and write the JSON+MD pair. Use after \`@page-author\` returns a body+metadata in draft mode.
+- \`create_page({workspace, stem, title, type, layout, learningObjectives, files?, markdownBody, chapterFolder?})\` — stamp a page JSON with a fresh v4 UUID and write the JSON+MD pair. Use after \`@page-author\` returns a body+metadata in draft mode. Validates freeze directive syntax before writing — will throw if FREEZE CODE BEGIN/END are unmatched or use wrong comment prefix for the language.
 - \`create_assessment({type, workspace, payload})\` — stamp an assessment JSON with a fresh taskId and write to \`.guides/assessments/\`. Returns \`{ taskId, jsonPath, embedLine }\`. Use after \`@assessment-author\` returns a payload. The returned \`embedLine\` is what you splice into the page markdown.
 - \`validate_guide({workspace})\` — deterministic structural validation (UUIDs, order arrays, embed references, taskId/filename consistency). Run automatically at the end of new-assignment, import-source, and reorder workflows. Run manually on user request (\`/validate-guide\`).
 </Tools>
@@ -142,7 +143,7 @@ Phases (which apply depends on the user's intent; the workflow-* skills give per
 1. **Intake** — confirm topic, audience, LOs, structural constraints, source materials. Do not skip; confirm even if some info was in the user's first message.
 2. **Outline Gate** — for new assignments or substantial restructures, \`@outline-architect\` returns a proposed outline. **Block until the user approves.** No file writes until then.
 3. **Scaffold** — once approved, generate stems (kebab-slug + 4-hex). Build the planning map. Write the root \`.guides/content/index.json\` (and the single chapter folder's index if applicable).
-4. **Drafting** — fan out \`@page-author\` (draft mode) for each page. Use \`create_page\` to stamp each. Run in parallel where pages are independent.
+4. **Drafting** — fan out \`@page-author\` (draft mode) for each page. Pass \`layoutConfig: { openFiles: files }\` derived from that page's \`files\` list. Use \`create_page\` to stamp each. Run in parallel where pages are independent.
 5. **Assessments** — for each page needing one, fan out \`@assessment-author\`. Use \`create_assessment\` for each returned payload. Splice the returned \`embedLine\` into the page markdown using the edit tool. Group multiple embeds under a \`## Check your understanding\` heading.
 6. **Validation** — run \`validate_guide\` tool (always at end of new-assignment / import-source / reorder workflows). Optionally delegate to \`@validator\` for content review when scope warrants.
 7. **Done** — summarize what was built and any flagged issues.
@@ -295,6 +296,7 @@ The orchestrator gives you:
 - \`title\`, \`type\`, \`layout\`, \`learningObjectives\`.
 - \`body_brief\` — bullets describing what the page should cover.
 - \`assignment_context\` — short summary of the assignment and what came before this page.
+- \`layoutConfig\` *(optional)* — \`{ openFiles: string[], panels: [] }\` — which files are open by default in Codio. Use this for adaptive file instructions (see Rule 3 below).
 
 What you return:
 - \`markdownBody\` — the full instructional prose.
@@ -302,9 +304,47 @@ What you return:
 
 You do **not** insert assessment embed strings. The orchestrator inserts those after \`assessment-author\` returns.
 
+## Codio Idioms (Cardinal Rules)
+
+These rules apply to **every page** you generate in draft mode.
+
+### Rule 1 — Freeze code directives
+
+When a code block is scaffold or starter code students must not modify:
+- Wrap with language-correct freeze directives:
+  - Python / Bash / Ruby: \`# FREEZE CODE BEGIN\` … \`# FREEZE CODE END\`
+  - JavaScript / TypeScript / Java / C / C++: \`// FREEZE CODE BEGIN\` … \`// FREEZE CODE END\`
+  - SQL: \`-- FREEZE CODE BEGIN\` … \`-- FREEZE CODE END\`
+- Signal: source comments like \`# DO NOT ALTER THIS CODE\` or context like "starter code" identify freeze-worthy regions.
+- Frozen code shows a padlock icon in Codio; students cannot edit it.
+- Do **not** add a Try It button to frozen blocks.
+
+### Rule 2 — Try It buttons
+
+For every executable code block that is **not frozen**, append a Try It button immediately after the closing fence:
+- Syntax: \`{Try it}(COMMAND)\` — no space between \`{Try it}\` and the parentheses.
+- Language commands: \`python3 solution.py\` / \`node solution.js\` / \`javac Main.java && java Main\`
+- Skip Try It for pseudocode, non-executable snippets, and frozen blocks.
+
+### Rule 3 — Adaptive file instructions
+
+Before writing any instruction that references a file:
+- If \`layoutConfig.openFiles\` contains that file → write **"Look at the X file on the left"**.
+- If the file is absent from \`openFiles\`, or no \`layoutConfig\` was provided → write **"Open the X file on the left"**.
+
+### Rule 4 — No duplicate page title
+
+- The page title (JSON \`title\` field) is the canonical H1.
+- Do **not** start your \`markdownBody\` with a \`# Heading\` that repeats the title.
+- Begin the body with prose or an H2, never a duplicate H1.
+
+### Rule 5 — Visualizer file references
+
+- Reference visualizer HTML files by local path only: e.g. \`"url": "tree_visualizer.html"\`.
+- Do **not** use full URLs (\`http://…\`) or \`preview:\` schemes.
+
 ## Style rules
 
-- Heading 1 = page title (matches the JSON \`title\`).
 - One concept per page. If you find yourself introducing a second major concept, stop — that's a separate page.
 - Worked examples in fenced code blocks with a language label.
 - "You" not "the student". Active voice. No filler.
@@ -1087,6 +1127,51 @@ async function createAssessmentHandler(raw) {
 import { unlinkSync, writeFileSync as writeFileSync2 } from "node:fs";
 import { join as join4 } from "node:path";
 import { z as z3 } from "zod";
+var LANG_COMMENT_PREFIX = {
+  python: "#",
+  py: "#",
+  bash: "#",
+  sh: "#",
+  ruby: "#",
+  rb: "#",
+  javascript: "//",
+  js: "//",
+  typescript: "//",
+  ts: "//",
+  java: "//",
+  c: "//",
+  cpp: "//",
+  "c++": "//",
+  sql: "--"
+};
+function validateFreezeDirectives(markdownBody) {
+  const errors = [];
+  const fenceRe = /^```(\w*)\n([\s\S]*?)^```/gm;
+  let match;
+  while ((match = fenceRe.exec(markdownBody)) !== null) {
+    const lang = (match[1] ?? "").toLowerCase();
+    const code = match[2] ?? "";
+    const beginCount = (code.match(/FREEZE CODE BEGIN/g) ?? []).length;
+    const endCount = (code.match(/FREEZE CODE END/g) ?? []).length;
+    if (beginCount !== endCount) {
+      errors.push(`\`\`\`${lang || "code"} block has unmatched freeze directives: ${beginCount} FREEZE CODE BEGIN, ${endCount} FREEZE CODE END`);
+      continue;
+    }
+    if (beginCount === 0)
+      continue;
+    const expectedPrefix = LANG_COMMENT_PREFIX[lang];
+    if (!expectedPrefix)
+      continue;
+    for (const m of code.matchAll(/^(.+?)FREEZE CODE BEGIN/gm)) {
+      const actualPrefix = (m[1] ?? "").trim();
+      if (actualPrefix !== expectedPrefix) {
+        errors.push(`Wrong comment prefix for FREEZE CODE in \`\`\`${lang} block: found "${actualPrefix}", expected "${expectedPrefix}"`);
+        break;
+      }
+    }
+  }
+  return errors;
+}
 var PAGE_TYPES = [
   "intro",
   "objectives",
@@ -1151,6 +1236,12 @@ function writeCreatedPage(workspace, chapterFolder, input) {
 }
 async function createPageHandler(raw) {
   const input = createPageInputSchema.parse(raw);
+  const freezeErrors = validateFreezeDirectives(input.markdownBody);
+  if (freezeErrors.length > 0) {
+    throw new Error(`Freeze directive validation failed:
+${freezeErrors.join(`
+`)}`);
+  }
   return writeCreatedPage(input.workspace, input.chapterFolder, input);
 }
 
@@ -1175,6 +1266,23 @@ function walkJsonFiles(root) {
   }
   return out;
 }
+var LANG_COMMENT_PREFIX2 = {
+  python: "#",
+  py: "#",
+  bash: "#",
+  sh: "#",
+  ruby: "#",
+  rb: "#",
+  javascript: "//",
+  js: "//",
+  typescript: "//",
+  ts: "//",
+  java: "//",
+  c: "//",
+  cpp: "//",
+  "c++": "//",
+  sql: "--"
+};
 function walkMdFiles(root) {
   if (!existsSync3(root))
     return [];
@@ -1205,6 +1313,49 @@ function collectIdFields(value, out) {
     collectIdFields(v, out);
   }
 }
+function findFirstH1(markdown) {
+  const match = markdown.match(/^# (.+)$/m);
+  return match ? (match[1] ?? "").trim() : null;
+}
+function checkFreezeDirectives(markdown) {
+  const errors = [];
+  const fenceRe = /^```(\w*)\n([\s\S]*?)^```/gm;
+  let match;
+  while ((match = fenceRe.exec(markdown)) !== null) {
+    const lang = (match[1] ?? "").toLowerCase();
+    const code = match[2] ?? "";
+    const beginCount = (code.match(/FREEZE CODE BEGIN/g) ?? []).length;
+    const endCount = (code.match(/FREEZE CODE END/g) ?? []).length;
+    if (beginCount !== endCount) {
+      errors.push(`\`\`\`${lang || "code"} block: ${beginCount} FREEZE CODE BEGIN vs ${endCount} FREEZE CODE END`);
+      continue;
+    }
+    if (beginCount === 0)
+      continue;
+    const expectedPrefix = LANG_COMMENT_PREFIX2[lang];
+    if (!expectedPrefix)
+      continue;
+    for (const m of code.matchAll(/^(.+?)FREEZE CODE BEGIN/gm)) {
+      const actualPrefix = (m[1] ?? "").trim();
+      if (actualPrefix !== expectedPrefix) {
+        errors.push(`\`\`\`${lang} block uses "${actualPrefix} FREEZE CODE BEGIN", expected "${expectedPrefix} FREEZE CODE BEGIN"`);
+        break;
+      }
+    }
+  }
+  return errors;
+}
+function findMalformedTryIt(markdown) {
+  const errors = [];
+  const re = /\{Try it\}(?!\()/g;
+  let m;
+  while ((m = re.exec(markdown)) !== null) {
+    const lineNum = markdown.slice(0, m.index).split(`
+`).length;
+    errors.push(`Line ~${lineNum}: {Try it} missing command parentheses — expected {Try it}(command)`);
+  }
+  return errors;
+}
 async function validateGuideHandler(raw) {
   const input = validateGuideInputSchema.parse(raw);
   const { guides, content, assessments } = resolveCodioPaths({
@@ -1295,7 +1446,75 @@ async function validateGuideHandler(raw) {
       }
     }
   }
-  return { findings, passed: findings.length === 0 };
+  for (const f of walkJsonFiles(content)) {
+    if (f.endsWith("/index.json"))
+      continue;
+    let pageTitle;
+    try {
+      const parsed = JSON.parse(readFileSync2(f, "utf8"));
+      pageTitle = parsed?.title;
+    } catch {
+      continue;
+    }
+    if (!pageTitle)
+      continue;
+    const mdPath = f.replace(/\.json$/, ".md");
+    if (!existsSync3(mdPath))
+      continue;
+    const body = readFileSync2(mdPath, "utf8");
+    const firstH1 = findFirstH1(body);
+    if (firstH1 && firstH1 === pageTitle) {
+      findings.push({
+        category: "double_header",
+        detail: `${relative(input.workspace, mdPath)}: first H1 "${firstH1}" duplicates page title — remove H1 from body`,
+        severity: "warning"
+      });
+    }
+  }
+  for (const md of walkMdFiles(content)) {
+    const body = readFileSync2(md, "utf8");
+    for (const err of checkFreezeDirectives(body)) {
+      findings.push({
+        category: "freeze_syntax_error",
+        detail: `${relative(input.workspace, md)}: ${err}`,
+        severity: "error"
+      });
+    }
+  }
+  for (const md of walkMdFiles(content)) {
+    const body = readFileSync2(md, "utf8");
+    for (const err of findMalformedTryIt(body)) {
+      findings.push({
+        category: "try_it_syntax_error",
+        detail: `${relative(input.workspace, md)}: ${err}`,
+        severity: "error"
+      });
+    }
+  }
+  for (const f of walkJsonFiles(content)) {
+    if (f.endsWith("/index.json"))
+      continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(readFileSync2(f, "utf8"));
+    } catch {
+      continue;
+    }
+    for (const entry of parsed?.files ?? []) {
+      const filePath = entry?.path;
+      if (!filePath)
+        continue;
+      if (!existsSync3(join5(input.workspace, filePath))) {
+        findings.push({
+          category: "missing_referenced_file",
+          detail: `${relative(input.workspace, f)}: references file "${filePath}" which does not exist in workspace`,
+          severity: "warning"
+        });
+      }
+    }
+  }
+  const errorCount = findings.filter((f) => f.severity === "error").length;
+  return { findings, passed: errorCount === 0 };
 }
 
 // src/tools/index.ts

package/dist/tools/create-page.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+export declare function validateFreezeDirectives(markdownBody: string): string[];
 export declare const PAGE_TYPES: readonly ["intro", "objectives", "instructional", "assessment", "conclusion"];
 export declare const PAGE_LAYOUTS: readonly ["1-panel", "2-panels-tree"];
 export declare const createPageInputSchema: z.ZodObject<{

package/dist/tools/create-page.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-page.d.ts","sourceRoot":"","sources":["../../src/tools/create-page.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,UAAU,+EAMb,CAAC;AAEX,eAAO,MAAM,YAAY,uCAAwC,CAAC;AAElE,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;iBAuB/B,CAAC;AAEJ,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,UAAU,CAAC;IACxB,MAAM,EAAE,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;IACtC,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,eAAe,GAAG,QAAQ,CAgB9D;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,KAAK,EAAE,eAAe,GACrB,gBAAgB,CA6BlB;AAED,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,gBAAgB,CAAC,CAG3B"}
+{"version":3,"file":"create-page.d.ts","sourceRoot":"","sources":["../../src/tools/create-page.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAWxB,wBAAgB,wBAAwB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE,CA6BvE;AAED,eAAO,MAAM,UAAU,+EAMb,CAAC;AAEX,eAAO,MAAM,YAAY,uCAAwC,CAAC;AAElE,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;iBAuB/B,CAAC;AAEJ,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,UAAU,CAAC;IACxB,MAAM,EAAE,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;IACtC,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,eAAe,GAAG,QAAQ,CAgB9D;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,KAAK,EAAE,eAAe,GACrB,gBAAgB,CA6BlB;AAED,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,gBAAgB,CAAC,CAO3B"}

package/dist/tools/validate-guide.d.ts

@@ -3,7 +3,7 @@ export declare const validateGuideInputSchema: z.ZodObject<{
     workspace: z.ZodString;
 }, z.core.$strip>;
 export type ValidateGuideInput = z.infer<typeof validateGuideInputSchema>;
-export type FindingCategory = 'missing_content_dir' | 'invalid_uuid' | 'orphan_order_stem' | 'broken_assessment_ref' | 'taskid_filename_mismatch';
+export type FindingCategory = 'missing_content_dir' | 'invalid_uuid' | 'orphan_order_stem' | 'broken_assessment_ref' | 'taskid_filename_mismatch' | 'double_header' | 'freeze_syntax_error' | 'try_it_syntax_error' | 'missing_referenced_file';
 export interface Finding {
     category: FindingCategory;
     detail: string;

package/dist/tools/validate-guide.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-guide.d.ts","sourceRoot":"","sources":["../../src/tools/validate-guide.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,eAAO,MAAM,wBAAwB;;iBAEnC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,MAAM,MAAM,eAAe,GACvB,qBAAqB,GACrB,cAAc,GACd,mBAAmB,GACnB,uBAAuB,GACvB,0BAA0B,CAAC;AAE/B,MAAM,WAAW,OAAO;IACtB,QAAQ,EAAE,eAAe,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;CAC/B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;CACjB;AAyCD,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,mBAAmB,CAAC,CAwG9B"}
+{"version":3,"file":"validate-guide.d.ts","sourceRoot":"","sources":["../../src/tools/validate-guide.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,eAAO,MAAM,wBAAwB;;iBAEnC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,MAAM,MAAM,eAAe,GACvB,qBAAqB,GACrB,cAAc,GACd,mBAAmB,GACnB,uBAAuB,GACvB,0BAA0B,GAC1B,eAAe,GACf,qBAAqB,GACrB,qBAAqB,GACrB,yBAAyB,CAAC;AAE9B,MAAM,WAAW,OAAO;IACtB,QAAQ,EAAE,eAAe,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;CAC/B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;CACjB;AAgGD,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,mBAAmB,CAAC,CA+K9B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codio-ai/opencode-authoring-agent",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Opencode plugin for authoring Codio guide assignments — orchestrator, subagents, tools, and skills.",
   "type": "module",
   "main": "dist/index.js",
@@ -11,19 +11,13 @@
       "types": "./dist/index.d.ts"
     }
   },
-  "files": [
-    "dist",
-    "src/skills",
-    "bin",
-    "README.md",
-    "LICENSE"
-  ],
+  "files": ["dist", "src/skills", "bin", "README.md", "LICENSE"],
   "bin": {
-    "codio-authoring-register": "bin/codio-authoring-register.js",
-    "codio-authoring-unregister": "bin/codio-authoring-unregister.js"
+    "codio-authoring-register": "./bin/codio-authoring-register.js",
+    "codio-authoring-unregister": "./bin/codio-authoring-unregister.js"
   },
   "scripts": {
-    "build": "bun build src/index.ts --outdir dist --target node --format esm --external @opencode-ai/plugin --external @opencode-ai/sdk --external zod && tsc --emitDeclarationOnly",
+    "build": "bun build src/index.ts --outdir dist --target node --format esm --external @opencode-ai/plugin --external @opencode-ai/sdk --external zod && bun build src/codio-scripts/codio-fetch.js src/codio-scripts/codio-publish.js --outdir dist/codio-scripts --target node --format esm && tsc --emitDeclarationOnly",
     "postinstall": "node ./bin/codio-authoring-register.js || true",
     "preuninstall": "node ./bin/codio-authoring-unregister.js || true",
     "test": "bun test",
@@ -33,17 +27,11 @@
     "check": "biome check --write .",
     "check:ci": "biome check ."
   },
-  "keywords": [
-    "opencode",
-    "opencode-plugin",
-    "codio",
-    "assignment-authoring",
-    "education"
-  ],
+  "keywords": ["opencode", "opencode-plugin", "codio", "assignment-authoring", "education"],
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/codio-extensions/codio-authoring-opencode-plugin.git"
+    "url": "https://github.com/codio-extensions/codio-authoring-opencode-plugin.git"
   },
   "homepage": "https://github.com/codio-extensions/codio-authoring-opencode-plugin#readme",
   "bugs": "https://github.com/codio-extensions/codio-authoring-opencode-plugin/issues",
@@ -61,6 +49,8 @@
     "@biomejs/biome": "2.4.11",
     "@types/node": "^24.6.1",
     "bun-types": "1.3.12",
+    "codio-api-js": "^0.18.0",
+    "json-2-csv": "^5.5.10",
     "typescript": "^5.9.3",
     "zod": "~4.1.0"
   },

package/src/skills/codio-fetch/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: codio-fetch
+description: Fetch and export an existing Codio course into an AI-ready local project. Use when the user asks to fetch, export, download, pull, or import a course from Codio, or to create a local AI-ready project from an existing Codio course.
+argument-hint: [--course-id <id>] [--output-dir <path>] [--domain <domain>]
+allowed-tools: [Bash, Read, Write, Edit]
+---
+
+# Codio Fetch
+
+Export an existing Codio course into a clean, AI-ready local project that can be edited and re-published with `codio-publish`.
+
+## What this skill does
+
+1. Loads credentials from `.env` at the workspace root (the Codio assignment directory).
+2. Authenticates with the Codio API using `CODIO_CLIENT_ID` and `CODIO_CLIENT_SECRET`.
+3. Fetches course metadata and builds a `course-manifest.json` with all module and assignment IDs.
+4. Downloads the course source export ZIP from Codio.
+5. Extracts the ZIP into `course-content/`, expanding nested `.tar.zst` assignment archives.
+6. Writes `course-assignments.csv` as a flat index for easy review.
+7. Cleans up temporary download files.
+
+The output is a self-contained project folder ready for `codio-publish` to read back.
+
+## Output structure
+
+```
+<output-dir>/                  ← default: ./course-project
+├── course-manifest.json       ← machine-readable index with all IDs and paths
+├── course-assignments.csv     ← flat CSV listing all modules and assignments
+└── course-content/
+    └── <module-folder>/
+        └── <assignment-folder>/
+            └── .guides/       ← guide pages, assessments, images
+```
+
+The `<output-dir>` is always a named subfolder, never at the workspace root itself.
+
+## Prerequisites
+
+Before running, verify:
+
+1. **`.env` file** — must exist at the workspace root:
+   ```
+   CODIO_CLIENT_ID=your-client-id
+   CODIO_CLIENT_SECRET=your-client-secret
+   CODIO_COURSE_ID=your-course-id      # optional if passing --course-id
+   CODIO_DOMAIN=codio.com              # optional, defaults to codio.com
+   ```
+   The script finds `.env` by walking up from the current directory, so it works from anywhere inside the workspace.
+
+2. **Check `.env` is in place:**
+   ```bash
+   [ -f .env ] && echo "found" || echo "missing — create .env before running"
+   ```
+
+3. **Required system tools:** `node`, `unzip`, `tar`, `find`
+
+## Running the export
+
+Run from the workspace root (the Codio assignment directory):
+
+```bash
+bash ~/.config/opencode/skills/codio-fetch/scripts/run-course-export.sh --course-id <id>
+```
+
+### Options
+
+| Option | Description |
+|---|---|
+| `--course-id <id>` | Codio course ID (overrides `CODIO_COURSE_ID` from `.env`) |
+| `--output-dir <path>` | Output project folder (default: `./course-project`) |
+| `--domain <domain>` | Codio domain (default: `codio.com` or `CODIO_DOMAIN` from `.env`) |
+
+### Examples
+
+```bash
+# Use course ID from .env, output to ./course-project
+bash ~/.config/opencode/skills/codio-fetch/scripts/run-course-export.sh
+
+# Specify course ID and custom output folder
+bash ~/.config/opencode/skills/codio-fetch/scripts/run-course-export.sh \
+  --course-id c87b4540de108faad55c8cefe7847492 \
+  --output-dir ./my-java-course
+
+# Use a staging Codio domain
+bash ~/.config/opencode/skills/codio-fetch/scripts/run-course-export.sh \
+  --course-id c87b4540de108faad55c8cefe7847492 \
+  --domain codio.co.uk
+```
+
+## How credentials are loaded
+
+The shell script walks up from the current directory looking for `.env`, then sources it with `set -a; . .env; set +a`. Values in `.env` **override** anything already in the environment.
+
+The `.env` is shared across all Codio skills (`codio-fetch`, `codio-publish`). There is one `.env` at the workspace root, not one per skill.
+
+## Environment variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `CODIO_CLIENT_ID` | Yes | Codio API client ID |
+| `CODIO_CLIENT_SECRET` | Yes | Codio API client secret |
+| `CODIO_COURSE_ID` | No | Course ID (can be passed as `--course-id` instead) |
+| `CODIO_DOMAIN` | No | Codio domain, default `codio.com` |
+
+## After the export
+
+- Open `<output-dir>/course-manifest.json` to see the full module/assignment hierarchy with IDs.
+- Open `<output-dir>/course-assignments.csv` for a flat spreadsheet view.
+- Assignment content is in `<output-dir>/course-content/<module>/<assignment>/`.
+- Use `codio-publish` to push edits back to Codio — the manifest with existing IDs is already in place.
+
+## Troubleshooting
+
+| Error | Fix |
+|---|---|
+| `Missing required environment variable: CODIO_CLIENT_ID` | Create or fix `.env` at workspace root |
+| `Missing course id` | Pass `--course-id <id>` or set `CODIO_COURSE_ID` in `.env` |
+| `Required command not found: unzip` | Install `unzip` via your package manager |
+| API 401 / auth error | Credentials in `.env` are invalid or expired |
+
+## Manifest format
+
+`course-manifest.json` produced by this skill is directly compatible with `codio-publish`. All assignment IDs are pre-populated, so a subsequent publish run will update existing assignments rather than create new ones.
+
+```jsonc
+{
+  "schemaVersion": 2,
+  "courseId": "...",
+  "exportedAt": "...",
+  "counts": { "modules": 2, "assignments": 6 },
+  "paths": {
+    "assignmentsCsv": "course-assignments.csv",
+    "courseContent": "course-content"
+  },
+  "modules": [
+    {
+      "name": "Module Name",
+      "folder": "module-name",
+      "path": "course-content/module-name",
+      "assignmentCount": 3,
+      "assignments": [
+        {
+          "id": "...",
+          "name": "Assignment Name",
+          "folder": "assignment-name",
+          "path": "course-content/module-name/assignment-name"
+        }
+      ]
+    }
+  ]
+}
+```

package/src/skills/codio-fetch/scripts/extract-course-export.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+set -Eeuo pipefail
+shopt -s nullglob
+
+log() {
+  printf '[%s] %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$*"
+}
+
+fail() {
+  log "ERROR: $*"
+  exit 1
+}
+
+require_command() {
+  command -v "$1" >/dev/null 2>&1 || fail "Required command not found: $1"
+}
+
+extract_assignment_archives() {
+  local root_dir="$1"
+  local archive_count=0
+
+  while IFS= read -r -d '' archive_path; do
+    archive_count=$((archive_count + 1))
+
+    local archive_dir archive_name destination_dir
+    archive_dir="$(dirname "$archive_path")"
+    archive_name="$(basename "$archive_path")"
+    destination_dir="$archive_dir/${archive_name%.tar.zst}"
+
+    rm -rf "$destination_dir"
+    mkdir -p "$destination_dir"
+
+    log "Extracting nested archive ${archive_name}"
+    tar --zstd -xf "$archive_path" -C "$destination_dir"
+    rm -f "$archive_path"
+  done < <(find "$root_dir" -type f -name '*.tar.zst' -print0)
+
+  log "Expanded ${archive_count} nested assignment archive(s)"
+}
+
+main() {
+  require_command unzip
+  require_command tar
+  require_command find
+  require_command cp
+
+  local export_zip_path="${1:-}"
+  local staging_dir="${2:-}"
+  local visible_output_dir="${3:-}"
+
+  [[ -n "$export_zip_path" ]]   || fail 'Usage: extract-course-export.sh <export-zip-path> <staging-dir> <visible-output-dir>'
+  [[ -n "$staging_dir" ]]       || fail 'Missing staging directory'
+  [[ -n "$visible_output_dir" ]] || fail 'Missing visible output directory'
+  [[ -f "$export_zip_path" ]]   || fail "Export ZIP not found: $export_zip_path"
+
+  rm -rf "$staging_dir" "$visible_output_dir"
+  mkdir -p "$staging_dir" "$visible_output_dir"
+
+  log "Unzipping $(basename "$export_zip_path") into hidden staging"
+  unzip -q "$export_zip_path" -d "$staging_dir"
+
+  extract_assignment_archives "$staging_dir"
+
+  cp -R "$staging_dir"/. "$visible_output_dir"
+
+  log "Published extracted course content to $visible_output_dir"
+}
+
+main "$@"