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

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/fetch-course.d.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+export declare const fetchCourseInputSchema: z.ZodObject<{
+    workspace: z.ZodString;
+    courseId: z.ZodString;
+    outputDir: z.ZodOptional<z.ZodString>;
+    domain: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type FetchCourseInput = z.infer<typeof fetchCourseInputSchema>;
+export interface FetchCourseResult {
+    outputDir: string;
+    manifestPath: string;
+    assignmentsCsvPath: string;
+    moduleCount: number;
+    assignmentCount: number;
+}
+export declare function fetchCourseHandler(raw: unknown): Promise<FetchCourseResult>;
+//# sourceMappingURL=fetch-course.d.ts.map

package/dist/tools/fetch-course.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-course.d.ts","sourceRoot":"","sources":["../../src/tools/fetch-course.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,sBAAsB;;;;;iBAQjC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;CACzB;AAoED,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAoGjF"}

package/dist/tools/fetch-course.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=fetch-course.test.d.ts.map

package/dist/tools/fetch-course.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-course.test.d.ts","sourceRoot":"","sources":["../../src/tools/fetch-course.test.ts"],"names":[],"mappings":""}

package/dist/tools/index.d.ts

@@ -58,5 +58,41 @@ export declare const validate_guide: {
         workspace: string;
     }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
 };
+export declare const fetch_course: {
+    description: string;
+    args: {
+        workspace: import("zod").ZodString;
+        courseId: import("zod").ZodString;
+        outputDir: import("zod").ZodOptional<import("zod").ZodString>;
+        domain: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    execute(args: {
+        workspace: string;
+        courseId: string;
+        outputDir?: string | undefined;
+        domain?: string | undefined;
+    }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+};
+export declare const publish_course: {
+    description: string;
+    args: {
+        manifestPath: import("zod").ZodString;
+        dryRun: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        force: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        module: import("zod").ZodOptional<import("zod").ZodString>;
+        assignment: import("zod").ZodOptional<import("zod").ZodString>;
+        changelog: import("zod").ZodOptional<import("zod").ZodString>;
+        stack: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    execute(args: {
+        manifestPath: string;
+        dryRun?: boolean | undefined;
+        force?: boolean | undefined;
+        module?: string | undefined;
+        assignment?: string | undefined;
+        changelog?: string | undefined;
+        stack?: string | undefined;
+    }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+};
 export declare const tools: Record<string, unknown>;
 //# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAOtB,CAAC;AAOH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;CAkB5B,CAAC;AAIH,eAAO,MAAM,cAAc;;;;;;;;CAOzB,CAAC;AAQH,eAAO,MAAM,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAIzC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAYA,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAOtB,CAAC;AAOH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;CAkB5B,CAAC;AAIH,eAAO,MAAM,cAAc;;;;;;;;CAOzB,CAAC;AAIH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;CAOvB,CAAC;AAIH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;CAOzB,CAAC;AAQH,eAAO,MAAM,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAMzC,CAAC"}

package/dist/tools/publish-course.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+export declare const publishCourseInputSchema: z.ZodObject<{
+    manifestPath: z.ZodString;
+    dryRun: z.ZodOptional<z.ZodBoolean>;
+    force: z.ZodOptional<z.ZodBoolean>;
+    module: z.ZodOptional<z.ZodString>;
+    assignment: z.ZodOptional<z.ZodString>;
+    changelog: z.ZodOptional<z.ZodString>;
+    stack: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PublishCourseInput = z.infer<typeof publishCourseInputSchema>;
+export interface PublishCourseResult {
+    published: number;
+    created: number;
+    unchanged: number;
+    skipped: number;
+    dryRun: boolean;
+}
+export declare function publishCourseHandler(raw: unknown): Promise<PublishCourseResult>;
+//# sourceMappingURL=publish-course.d.ts.map

package/dist/tools/publish-course.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish-course.d.ts","sourceRoot":"","sources":["../../src/tools/publish-course.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,wBAAwB;;;;;;;;iBAQnC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AA6DD,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAoHrF"}

package/dist/tools/publish-course.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=publish-course.test.d.ts.map

package/dist/tools/publish-course.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish-course.test.d.ts","sourceRoot":"","sources":["../../src/tools/publish-course.test.ts"],"names":[],"mappings":""}

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.3",
   "description": "Opencode plugin for authoring Codio guide assignments — orchestrator, subagents, tools, and skills.",
   "type": "module",
   "main": "dist/index.js",
@@ -11,16 +11,10 @@
       "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",
@@ -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/reference-codio-api/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: reference-codio-api
+description: Reference for the Codio platform API tools — fetch_course and publish_course. Course manifest format, output structure, credential requirements, and troubleshooting. Use when working with fetched courses or publishing assignments.
+---
+
+# Codio API Tools Reference
+
+## Credentials
+
+Both tools read credentials from environment variables. Set these on the Codio box before using either tool:
+
+| Variable | Required | Description |
+|---|---|---|
+| `CODIO_CLIENT_ID` | Yes | Codio API client ID |
+| `CODIO_CLIENT_SECRET` | Yes | Codio API client secret |
+| `CODIO_DOMAIN` | No | Codio domain, default `codio.com` |
+
+---
+
+## `fetch_course` — Pull a course from Codio
+
+Authenticates with the Codio API, downloads the course export, and writes an AI-ready project to the workspace.
+
+### Inputs
+
+| Field | Required | Description |
+|---|---|---|
+| `workspace` | Yes | Absolute path to the Codio workspace root |
+| `courseId` | Yes | Codio course ID (32-char hex string) |
+| `outputDir` | No | Output folder name, default `course-project` |
+| `domain` | No | Codio domain, default `codio.com` |
+
+### Output
+
+Returns `{ outputDir, manifestPath, assignmentsCsvPath, moduleCount, assignmentCount }`.
+
+Writes to `<outputDir>/` inside the workspace:
+
+```
+<outputDir>/
+├── course-manifest.json       ← machine-readable index; source of truth for publish_course
+├── course-assignments.csv     ← flat CSV for review
+└── course-content/
+    └── <module-folder>/
+        └── <assignment-folder>/
+            └── .guides/       ← guide pages, assessments, images
+```
+
+---
+
+## `publish_course` — Push assignments back to Codio
+
+Reads `course-manifest.json` from the project folder and publishes each assignment to Codio.
+
+### Inputs
+
+| Field | Required | Description |
+|---|---|---|
+| `manifestPath` | Yes | Absolute path to `course-manifest.json` |
+| `dryRun` | No | Preview actions without making changes |
+| `force` | No | Publish all, bypassing change detection |
+| `module` | No | Only process this module (name or folder) |
+| `assignment` | No | Only process this assignment (name or folder) |
+| `changelog` | No | Changelog text applied to all publishes |
+| `stack` | No | Force a specific stack ID for all assignments |
+
+### Output
+
+Returns `{ published, created, unchanged, skipped }`.
+
+Writes back any new IDs to `course-manifest.json` immediately after each resource is created.
+
+### Change detection
+
+The tool skips existing assignments whose content hash matches the stored `contentHash` in the manifest. Pass `force: true` to bypass. New assignments (no `id`) are always published.
+
+### Stacks
+
+- **New assignments** always use the default stack.
+- **Existing assignments** preserve their current stack unless `stack` is supplied.
+
+---
+
+## course-manifest.json format
+
+Created by `fetch_course`, consumed by `publish_course`. Both tools write back IDs as resources are created/resolved.
+
+```jsonc
+{
+  "schemaVersion": 2,
+  "courseId": "c87b4540de108faad55c8cefe7847492",
+  "exportedAt": "2026-06-12T10:00:00.000Z",
+  "counts": { "modules": 2, "assignments": 6 },
+  "paths": {
+    "assignmentsCsv": "course-assignments.csv",
+    "courseContent": "course-content"
+  },
+  "modules": [
+    {
+      "id": "...",             // Resolved or created by publish_course; written back
+      "name": "Module Name",
+      "folder": "module-name",
+      "path": "course-content/module-name",
+      "assignmentCount": 3,
+      "assignments": [
+        {
+          "id": "...",          // Created by publish_course if empty; written back
+          "name": "Assignment Name",
+          "folder": "assignment-name",
+          "path": "course-content/module-name/assignment-name",
+          "contentHash": "..."  // Written after each successful publish; used for change detection
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Folder slug rules
+
+Codio uses lowercase slugs: normalise to ASCII, lowercase, replace each non-alphanumeric character with `-`, trim leading/trailing hyphens. Example: `"1.1 – Intro"` → `"1-1---intro"`.
+
+---
+
+## Typical workflow
+
+```
+fetch_course(courseId)
+  → course-project/course-manifest.json + course-content/...
+
+[edit assignment pages using authoring tools]
+
+publish_course(manifestPath, dryRun: true)   ← preview first
+publish_course(manifestPath)                 ← publish for real
+```
+
+---
+
+## Troubleshooting
+
+| Error | Fix |
+|---|---|
+| `CODIO_CLIENT_ID ... must be set` | Set env vars on the box |
+| `course-manifest.json not found` | Pass the absolute path to the manifest; run from or inside the project folder |
+| `path not found` for an assignment | The folder referenced in the manifest doesn't exist — generate content there first |
+| `Required command not found: unzip` | Install `unzip` via the box package manager |
+| API 401 / auth error | Credentials are invalid or expired |
+| API 429 rate limit | Library retries automatically; wait and re-run if still failing |
+| `no module ID available` | Module creation failed earlier in the run — check the error above it |