@open-press/cli 0.3.0 → 0.6.0

package/template/core/engine/commands/doctor.mjs

@@ -0,0 +1,229 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24h
+const CORE_PACKAGE = "@open-press/core";
+
+export async function run({ root, options }) {
+  const json = Boolean(options?.json);
+  const noCache = Boolean(options?.noCache);
+
+  const report = await diagnose(root, { noCache });
+
+  if (json) {
+    process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+  } else {
+    printHumanReport(report);
+  }
+
+  // Exit 0 even when stale — doctor is informational, not a gate.
+  // Agents / CI can check report.stale or report.coreUpdateAvailable.
+  return 0;
+}
+
+/**
+ * Diagnose workspace against latest framework state.
+ * Result shape:
+ *   {
+ *     coreVersion: "0.4.0",                    // installed
+ *     coreLatest: "0.5.0" | null,              // null on network failure
+ *     coreUpdateAvailable: boolean,
+ *     skillsInstalled: ["openpress", ...],
+ *     skillsLockSource: "quan0715/open-press" | null,
+ *     pendingMigrations: ["0.5.0"],            // versions with docs/migrations notes
+ *     stale: boolean,                          // either core or skills behind
+ *     cachedAt: ISO timestamp
+ *   }
+ */
+export async function diagnose(root, { noCache = false } = {}) {
+  const cachePath = path.join(root, ".openpress", "cache", "doctor.json");
+
+  if (!noCache) {
+    const cached = await readCached(cachePath);
+    if (cached) return cached;
+  }
+
+  const coreVersion = await readCoreVersion(root);
+  const coreLatest = await fetchCoreLatest();
+  const skillsInstalled = await listInstalledSkills(root);
+  const skillsLockSource = await readSkillsLockSource(root);
+  const pendingMigrations = await listPendingMigrations(root, coreVersion, coreLatest);
+
+  const coreUpdateAvailable = Boolean(
+    coreVersion && coreLatest && coreVersion !== coreLatest && semverLt(coreVersion, coreLatest),
+  );
+
+  const report = {
+    coreVersion,
+    coreLatest,
+    coreUpdateAvailable,
+    skillsInstalled,
+    skillsLockSource,
+    pendingMigrations,
+    stale: coreUpdateAvailable || pendingMigrations.length > 0,
+    cachedAt: new Date().toISOString(),
+  };
+
+  await writeCached(cachePath, report).catch(() => {});
+  return report;
+}
+
+async function readCached(cachePath) {
+  try {
+    const stats = await stat(cachePath);
+    if (Date.now() - stats.mtimeMs > CACHE_TTL_MS) return null;
+    return JSON.parse(await readFile(cachePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+async function writeCached(cachePath, report) {
+  await mkdir(path.dirname(cachePath), { recursive: true });
+  await writeFile(cachePath, JSON.stringify(report, null, 2) + "\n", "utf8");
+}
+
+async function readCoreVersion(root) {
+  // Try workspace package.json deps first; fall back to installed package.
+  try {
+    const pkg = JSON.parse(await readFile(path.join(root, "package.json"), "utf8"));
+    const range = pkg.dependencies?.[CORE_PACKAGE] ?? pkg.devDependencies?.[CORE_PACKAGE];
+    if (range) {
+      // Try the installed version (more accurate than the range).
+      try {
+        const installed = JSON.parse(
+          await readFile(path.join(root, "node_modules", CORE_PACKAGE, "package.json"), "utf8"),
+        );
+        return installed.version;
+      } catch {
+        return range.replace(/^[\^~>=<\s]+/, "");
+      }
+    }
+  } catch {}
+
+  // Self-bundled framework (cli scaffolded workspace): pkg.version is the framework version.
+  try {
+    const pkg = JSON.parse(await readFile(path.join(root, "package.json"), "utf8"));
+    if (pkg.name === CORE_PACKAGE) return pkg.version;
+  } catch {}
+
+  return null;
+}
+
+async function fetchCoreLatest() {
+  try {
+    const res = await fetch(`https://registry.npmjs.org/${CORE_PACKAGE}/latest`, {
+      headers: { Accept: "application/json" },
+      signal: AbortSignal.timeout(5000),
+    });
+    if (!res.ok) return null;
+    const data = await res.json();
+    return typeof data.version === "string" ? data.version : null;
+  } catch {
+    return null;
+  }
+}
+
+async function listInstalledSkills(root) {
+  const skillsDir = path.join(root, ".agents", "skills");
+  try {
+    const { readdir } = await import("node:fs/promises");
+    const entries = await readdir(skillsDir, { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory()).map((e) => e.name).sort();
+  } catch {
+    return [];
+  }
+}
+
+async function readSkillsLockSource(root) {
+  try {
+    const lock = JSON.parse(await readFile(path.join(root, "skills-lock.json"), "utf8"));
+    const sources = lock?.sources;
+    if (Array.isArray(sources) && sources.length > 0) return sources[0]?.source ?? null;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+async function listPendingMigrations(root, currentVersion, latestVersion) {
+  if (!currentVersion || !latestVersion || !semverLt(currentVersion, latestVersion)) return [];
+  // Look for docs/migrations/<version>.md files for versions in (current, latest].
+  const migrationsDir = path.join(root, "docs", "migrations");
+  try {
+    const { readdir } = await import("node:fs/promises");
+    const files = await readdir(migrationsDir);
+    return files
+      .filter((f) => /^\d+\.\d+\.\d+\.md$/.test(f))
+      .map((f) => f.replace(/\.md$/, ""))
+      .filter((v) => semverGt(v, currentVersion) && !semverGt(v, latestVersion))
+      .sort(semverCompare);
+  } catch {
+    return [];
+  }
+}
+
+function semverParse(v) {
+  const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v);
+  if (!m) return [0, 0, 0];
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+function semverCompare(a, b) {
+  const A = semverParse(a);
+  const B = semverParse(b);
+  for (let i = 0; i < 3; i++) if (A[i] !== B[i]) return A[i] - B[i];
+  return 0;
+}
+function semverLt(a, b) { return semverCompare(a, b) < 0; }
+function semverGt(a, b) { return semverCompare(a, b) > 0; }
+
+function printHumanReport(report) {
+  const lines = [];
+  lines.push("○ open-press doctor");
+  lines.push("");
+  lines.push("framework");
+  if (report.coreVersion) {
+    if (report.coreLatest === null) {
+      lines.push(`  ? @open-press/core: ${report.coreVersion} installed (couldn't check latest — offline?)`);
+    } else if (report.coreUpdateAvailable) {
+      lines.push(`  ⚠ @open-press/core: ${report.coreVersion} installed → ${report.coreLatest} available`);
+    } else {
+      lines.push(`  ✓ @open-press/core: ${report.coreVersion} (latest)`);
+    }
+  } else {
+    lines.push("  ? @open-press/core: not detected in this workspace");
+  }
+  lines.push("");
+  lines.push("skills");
+  if (report.skillsInstalled.length === 0) {
+    lines.push("  ? no skills installed under .agents/skills/");
+    lines.push("    run: npx skills add quan0715/open-press");
+  } else {
+    lines.push(`  ✓ ${report.skillsInstalled.length} skills installed`);
+    if (report.skillsLockSource) {
+      lines.push(`    source: ${report.skillsLockSource}`);
+      lines.push("    refresh: npx skills upgrade");
+    }
+  }
+  lines.push("");
+  lines.push("migrations");
+  if (report.pendingMigrations.length === 0) {
+    if (report.coreUpdateAvailable) {
+      lines.push(`  ✓ no breaking migrations documented for the ${report.coreLatest} window`);
+    } else {
+      lines.push("  ✓ up to date");
+    }
+  } else {
+    lines.push(`  ⚠ ${report.pendingMigrations.length} migration note(s) since your version:`);
+    for (const v of report.pendingMigrations) lines.push(`    - docs/migrations/${v}.md`);
+  }
+  lines.push("");
+  if (report.stale) {
+    lines.push("next");
+    lines.push("  npx open-press upgrade        # apply all updates (agent-driven)");
+    lines.push("  npx open-press doctor --json  # machine-readable output");
+    lines.push("");
+  }
+  process.stdout.write(lines.join("\n"));
+}

package/template/core/engine/commands/pdf.mjs

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { buildReactPdf } from "./_shared.mjs";
+import { CLI_ENTRY, STATIC_SERVER, buildReactPdf, formatNodeScriptCommand } from "./_shared.mjs";
 
 export async function run({ root, config, options, recurse }) {
   const outputPath = options.output ? path.resolve(root, options.output) : undefined;
@@ -7,8 +7,8 @@ export async function run({ root, config, options, recurse }) {
     const relOutput = path.relative(root, outputPath ?? config.paths.pdf);
     const host = options.host ?? "127.0.0.1";
     const port = options.port ?? "5185";
-    console.log("Command: node engine/cli.mjs render . --renderer react");
-    console.log(`Command: node engine/static-server.mjs ${config.outputDir} --host ${host} --port ${port} --workspace .`);
+    console.log(`Command: ${formatNodeScriptCommand(root, CLI_ENTRY)} render . --renderer react`);
+    console.log(`Command: ${formatNodeScriptCommand(root, STATIC_SERVER)} ${config.outputDir} --host ${host} --port ${port} --workspace .`);
     console.log(`Command: Chrome --print-to-pdf=${relOutput} http://${host}:${port}/?print=1`);
     return 0;
   }

package/template/core/engine/commands/preview.mjs

@@ -1,4 +1,4 @@
-import { runCommand } from "./_shared.mjs";
+import { CLI_ENTRY, STATIC_SERVER, formatNodeScriptCommand, runCommand } from "./_shared.mjs";
 
 export async function run({ root, config, options, recurse }) {
   const renderer = options.renderer ?? "react";
@@ -12,9 +12,9 @@ export async function run({ root, config, options, recurse }) {
   if (options.dryRun) {
     console.log(`OpenPress preview URL: ${url}`);
     if (!options.noBuild) {
-      console.log("Command: node engine/cli.mjs render . --renderer react");
+      console.log(`Command: ${formatNodeScriptCommand(root, CLI_ENTRY)} render . --renderer react`);
     }
-    console.log(`Command: node engine/static-server.mjs ${config.outputDir} --host ${host} --port ${port} --workspace .`);
+    console.log(`Command: ${formatNodeScriptCommand(root, STATIC_SERVER)} ${config.outputDir} --host ${host} --port ${port} --workspace .`);
     return 0;
   }
   if (!options.noBuild) {
@@ -22,5 +22,5 @@ export async function run({ root, config, options, recurse }) {
     if (renderCode !== 0) return renderCode;
   }
   console.log(`OpenPress preview: ${url}`);
-  return runCommand("node", ["engine/static-server.mjs", config.outputDir, "--host", host, "--port", port, "--workspace", "."], root);
+  return runCommand("node", [STATIC_SERVER, config.outputDir, "--host", host, "--port", port, "--workspace", "."], root);
 }

package/template/core/engine/commands/upgrade.mjs

@@ -0,0 +1,117 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { diagnose } from "./doctor.mjs";
+import { runCommand } from "./_shared.mjs";
+
+export async function run({ root, options }) {
+  const dryRun = Boolean(options?.dryRun);
+  const skipSkills = Boolean(options?.noSkills);
+  const skipDeps = Boolean(options?.noDeps);
+  const json = Boolean(options?.json);
+
+  // 1. Fresh diagnose (force re-check, ignore cache).
+  const before = await diagnose(root, { noCache: true });
+
+  if (!before.stale) {
+    const message = "open-press is already up to date.";
+    if (json) {
+      process.stdout.write(JSON.stringify({ status: "noop", before }, null, 2) + "\n");
+    } else {
+      process.stdout.write(`✓ ${message}\n`);
+    }
+    return 0;
+  }
+
+  if (!json) {
+    process.stdout.write("○ open-press upgrade\n\n");
+    if (before.coreUpdateAvailable) {
+      process.stdout.write(
+        `  @open-press/core: ${before.coreVersion} → ${before.coreLatest}\n`,
+      );
+    }
+    if (before.pendingMigrations.length > 0) {
+      process.stdout.write(`  migration notes: ${before.pendingMigrations.join(", ")}\n`);
+    }
+    process.stdout.write("\n");
+  }
+
+  if (dryRun) {
+    if (!json) {
+      process.stdout.write("dry run — nothing changed. The agent should:\n");
+      process.stdout.write("  1. read each docs/migrations/<version>.md for document-level changes\n");
+      process.stdout.write("  2. apply edits to document/ where needed\n");
+      process.stdout.write("  3. re-run: npx open-press upgrade   (without --dry-run)\n");
+    } else {
+      process.stdout.write(JSON.stringify({ status: "dry-run", before }, null, 2) + "\n");
+    }
+    return 0;
+  }
+
+  // 2. Refresh framework dep (only when workspace declares @open-press/core).
+  if (!skipDeps && (await hasCoreDep(root))) {
+    if (!json) process.stdout.write("▸ updating @open-press/core via npm…\n");
+    const code = runCommand("npm", ["update", "@open-press/core"], root);
+    if (code !== 0) {
+      if (!json) process.stdout.write("  ⚠ npm update returned non-zero; continuing\n");
+    }
+  }
+
+  // 3. Refresh skills (npx skills upgrade respects skills-lock.json).
+  if (!skipSkills) {
+    if (!json) process.stdout.write("▸ refreshing skills via npx skills upgrade…\n");
+    runCommand("npx", ["-y", "skills@latest", "upgrade"], root);
+  }
+
+  // 4. Surface migration notes for the agent to read.
+  const migrationContents = await loadMigrations(root, before.pendingMigrations);
+
+  // 5. Re-diagnose to confirm the move.
+  const after = await diagnose(root, { noCache: true });
+
+  if (json) {
+    process.stdout.write(
+      JSON.stringify(
+        { status: "applied", before, after, migrationContents: migrationContents.map((m) => m.path) },
+        null,
+        2,
+      ) + "\n",
+    );
+    return 0;
+  }
+
+  process.stdout.write("\n✓ upgrade applied. Now read these migration notes:\n\n");
+  if (migrationContents.length === 0) {
+    process.stdout.write("  (no migration docs in this version range)\n\n");
+  } else {
+    for (const m of migrationContents) {
+      process.stdout.write(`  ─ ${m.path}\n`);
+    }
+    process.stdout.write(
+      "\nAgent: open each file, identify document-level changes, grep document/ for affected patterns, propose edits before applying.\n",
+    );
+  }
+
+  process.stdout.write("\nVerify with:\n  npm run openpress:validate\n  npm run openpress:render\n\n");
+  return 0;
+}
+
+async function hasCoreDep(root) {
+  try {
+    const pkg = JSON.parse(await readFile(path.join(root, "package.json"), "utf8"));
+    return Boolean(pkg.dependencies?.["@open-press/core"] || pkg.devDependencies?.["@open-press/core"]);
+  } catch {
+    return false;
+  }
+}
+
+async function loadMigrations(root, versions) {
+  const results = [];
+  for (const v of versions) {
+    const p = path.join(root, "docs", "migrations", `${v}.md`);
+    if (existsSync(p)) {
+      results.push({ version: v, path: path.relative(root, p) });
+    }
+  }
+  return results;
+}

package/template/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-press/core",
-  "version": "0.3.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "open-press core — runtime primitives, CLI, and render pipeline for AI-first fixed-layout documents.",
   "license": "MIT",
@@ -65,6 +65,8 @@
     "js-yaml": "^4.1.1",
     "katex": "^0.16.47",
     "lucide-react": "^1.16.0",
+    "playwright": "^1.60.0",
+    "postcss": "^8.5.6",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
     "rehype-katex": "^7.0.1",

package/template/core/vite.config.ts

@@ -9,13 +9,18 @@ import { loadConfig, publicPdfHref } from "./engine/config.mjs";
 import { handleCommentRequest } from "./engine/react/comment-endpoint.mjs";
 import { handleProjectAssetRequest } from "./engine/react/project-asset-endpoint.mjs";
 
-const sourceRoot = fileURLToPath(new URL("./src", import.meta.url));
-const workspaceRoot = fileURLToPath(new URL("./", import.meta.url));
-const openpressCoreEntry = fileURLToPath(new URL("./src/openpress/core/index.tsx", import.meta.url));
-const reactDocumentComponentsRoot = path.join(workspaceRoot, "document", "components");
+const frameworkRoot = fileURLToPath(new URL("./", import.meta.url));
+const workspaceRoot = process.env.OPENPRESS_WORKSPACE_ROOT
+  ? path.resolve(process.env.OPENPRESS_WORKSPACE_ROOT)
+  : frameworkRoot;
+const sourceRoot = path.join(frameworkRoot, "src");
+const openpressCliPath = path.join(frameworkRoot, "engine", "cli.mjs");
+const staticServerPath = path.join(frameworkRoot, "engine", "static-server.mjs");
+const openpressCoreEntry = path.join(frameworkRoot, "src", "openpress", "core", "index.tsx");
 const openpressConfig = await loadConfig(workspaceRoot);
 const outputDir = openpressConfig.paths.outputDir;
-const reactDocumentRoot = path.join(workspaceRoot, "document");
+const reactDocumentRoot = openpressConfig.paths.documentRoot;
+const reactDocumentComponentsRoot = openpressConfig.paths.componentsDir;
 const reactDocumentEntry = path.join(reactDocumentRoot, "index.tsx");
 const activeContentDir = await fileExists(reactDocumentEntry)
   ? path.join(reactDocumentRoot, "chapters")
@@ -48,6 +53,7 @@ export default defineConfig({
   plugins: [openpressLocalDeployPlugin(), react()],
   define: workspaceDefines,
   resolve: {
+    dedupe: ["react", "react-dom", "@mdx-js/react"],
     alias: {
       "@openpress/core": openpressCoreEntry,
       "@/components": reactDocumentComponentsRoot,
@@ -69,6 +75,9 @@ export default defineConfig({
   server: {
     host: "127.0.0.1",
     port: 5173,
+    fs: {
+      allow: Array.from(new Set([frameworkRoot, workspaceRoot])),
+    },
     watch: {
       ignored: ["**/.openpress/tmp/**", `**/${openpressConfig.outputDir}/**`],
     },
@@ -201,7 +210,7 @@ async function handleLocalPdfExportRequest(req: IncomingMessage, res: ServerResp
     ok: result.code === 0 && exists,
     code: result.code,
     pdf: `/__openpress/local-pdf-file?ts=${Date.now()}`,
-    command: "node engine/cli.mjs pdf .",
+    command: openpressCliCommand(["pdf", "."]),
     stdout: result.stdout,
     stderr: result.stderr,
   });
@@ -266,7 +275,7 @@ async function handleLocalDeployRequest(req: IncomingMessage, res: ServerRespons
       deploy_adapter: openpressConfig.deploy.adapter,
       deploy_source: openpressConfig.deploy.source,
       deploy_project_name: openpressConfig.deploy.projectName,
-      command: "node engine/cli.mjs deploy . --confirm",
+      command: openpressCliCommand(["deploy", ".", "--confirm"]),
     });
     return;
   }
@@ -285,7 +294,7 @@ async function handleLocalDeployRequest(req: IncomingMessage, res: ServerRespons
     pdf: deployedUrl ? `${deployedUrl}/${openpressConfig.pdf.filename}` : deploymentInfo.pdf,
     public_url: publicUrl,
     dirty: false,
-    command: "node engine/cli.mjs deploy . --confirm",
+    command: openpressCliCommand(["deploy", ".", "--confirm"]),
     stdout: result.stdout,
     stderr: result.stderr,
   });
@@ -293,7 +302,7 @@ async function handleLocalDeployRequest(req: IncomingMessage, res: ServerRespons
 
 function runLocalPdfExport() {
   return new Promise<{ code: number; stdout: string; stderr: string }>((resolve) => {
-    const child = spawn("node", ["engine/cli.mjs", "pdf", "."], {
+    const child = spawn("node", [openpressCliPath, "pdf", "."], {
       cwd: workspaceRoot,
       shell: false,
     });
@@ -316,7 +325,7 @@ function runLocalPdfExport() {
 
 function runLocalDeploy() {
   return new Promise<{ code: number; stdout: string; stderr: string }>((resolve) => {
-    const child = spawn("node", ["engine/cli.mjs", "deploy", ".", "--confirm"], {
+    const child = spawn("node", [openpressCliPath, "deploy", ".", "--confirm"], {
       cwd: workspaceRoot,
       shell: false,
     });
@@ -405,7 +414,7 @@ function getLocalDeploymentSourcePaths() {
     openpressConfig.paths.themeDir,
     openpressConfig.paths.designDoc,
     openpressConfig.paths.componentsDir,
-    path.join(workspaceRoot, "src"),
+    path.join(frameworkRoot, "src"),
     path.join(workspaceRoot, "index.html"),
     path.join(workspaceRoot, "package.json"),
     path.join(workspaceRoot, "openpress.config.mjs"),
@@ -414,6 +423,12 @@ function getLocalDeploymentSourcePaths() {
   ];
 }
 
+function openpressCliCommand(args: string[]) {
+  const relativeCliPath = path.relative(workspaceRoot, openpressCliPath).replaceAll("\\", "/");
+  const displayCliPath = relativeCliPath && !relativeCliPath.startsWith("../") ? relativeCliPath : openpressCliPath;
+  return `node ${displayCliPath} ${args.join(" ")}`;
+}
+
 async function findNewestLocalSourceMtime(paths: string[]) {
   const times = await Promise.all(paths.map((sourcePath) => findNewestLocalMtime(sourcePath)));
   return Math.max(0, ...times);

package/template/packs/academic-paper/document/chapters/01-introduction/content/01-introduction.mdx

@@ -0,0 +1,21 @@
+## Introduction
+
+This document is a model and starting point for an academic paper drafted in open-press. The structure follows the IEEE conference template conventions where they make sense for screen-first reading: numbered sections, italic sub-sections, an abstract block, and a numbered references list. The two-column body of IEEEtran is not yet supported — single-column will land as the v0.8 paged.js migration arrives.
+
+Use this pack for **drafting, iteration, and preprint distribution**. When the paper is ready for venue submission, export the prose into the publisher's required LaTeX class (`IEEEtran`, `acmart`, etc.). The pack does not replace LaTeX for camera-ready submission; it replaces the awkward iteration loop *before* submission.
+
+### Where to start
+
+Each chapter directory under `document/chapters/` is one paper section:
+
+- `01-introduction/` — motivate the work, state the contribution, summarise the structure.
+- `02-methods/` — describe what you did, with enough detail to reproduce.
+- `03-results-and-discussion/` — present results with figures and tables; interpret what they mean.
+- `04-acknowledgment/` — acknowledge funding, collaborators, reviewers.
+- `05-references/` — numbered `[1]`, `[2]` references.
+
+Replace each chapter's MDX content with your own. The skeleton text below each `##` heading is illustrative — overwrite it.
+
+### Abstract and Index Terms
+
+Edit the abstract and index terms inside `document/index.tsx` (the `cover` JSX export). They render on the title page above the body. Keep the abstract under 250 words and avoid abbreviations, symbols, or math in it.

package/template/packs/academic-paper/document/chapters/02-methods/content/01-methods.mdx

@@ -0,0 +1,30 @@
+## Methods
+
+Describe the materials, instruments, datasets, models, or procedures you used. Anyone familiar with the field should be able to reproduce your work from this section.
+
+### Apparatus and Materials
+
+Specify hardware, software versions, datasets, and any pre-processing. Cite reused work using `[N]` numeric references (e.g. "we trained the encoder following the procedure of [3]").
+
+### Procedure
+
+Describe the experimental procedure as steps a reader could follow:
+
+1. State the input data and pre-processing.
+2. State the model / algorithm / instrument settings.
+3. State the evaluation metric(s) and any held-out splits.
+4. State randomness control (seeds, repeats, confidence reporting).
+
+### Notation
+
+Define notation early. Italicise Roman symbols for quantities and variables, but not Greek symbols. Use a long dash rather than a hyphen for a minus sign. Number equations consecutively:
+
+$$a + b = \gamma \tag{1}$$
+
+Refer to equations by `(1)`, not `Eq. (1)` or `equation (1)`, except at the start of a sentence: "Equation (1) shows ...".
+
+### Reporting Units
+
+- Use SI (MKS) as primary units; English units only as secondary (in parentheses).
+- Don't mix complete spellings and abbreviations: "Wb/m²" or "webers per square meter", not "webers/m²".
+- Use a zero before decimal points: `0.25`, not `.25`.

package/template/packs/academic-paper/document/chapters/03-results-and-discussion/content/01-results.mdx

@@ -0,0 +1,29 @@
+## Results and Discussion
+
+Present the findings of your study, then interpret what they mean for the research question stated in the introduction.
+
+### Quantitative Results
+
+Use a table to summarise results across conditions. Caption above the table.
+
+<TableCaption>Sample comparison of conditions.</TableCaption>
+
+| Condition | Metric A | Metric B | Notes |
+| --- | --- | --- | --- |
+| Baseline | 0.71 | 0.65 | Prior work [3] |
+| Ours (v1) | 0.78 | 0.69 | This work |
+| Ours (v2) | **0.83** | **0.72** | Best |
+
+Cite figures and tables in the text the first time they appear: "Fig. 1 shows the architecture", "Table I summarises the conditions". Use `Fig.` even at the start of a sentence; spell out `Figure` only when it is the subject.
+
+### Qualitative Discussion
+
+Discuss what the results mean. State the limitations honestly — if the experiment doesn't cover a case you'd like to claim, say so. Avoid the word "essentially" when you mean "approximately" or "effectively".
+
+### Threats to Validity
+
+Briefly list what could invalidate the results: small sample size, single dataset, environmental drift, evaluator bias, etc. Reviewers will look for this section; pre-empt it.
+
+### Future Work
+
+Indicate where the work goes next. Keep this to one short paragraph — over-claiming future scope hurts more than it helps in review.

package/template/packs/academic-paper/document/chapters/04-acknowledgment/content/01-acknowledgment.mdx

@@ -0,0 +1,12 @@
+## Acknowledgment
+
+The preferred American spelling is *acknowledgment* without an "e" after the "g". Avoid stilted constructions like "one of us (R. B. G.) thanks ...". Prefer "R. B. G. thanks ...".
+
+Acknowledge:
+
+- Funding sources (with grant numbers if applicable).
+- Collaborators who contributed materially but are not listed as authors.
+- Anonymous reviewers whose comments improved the paper.
+- Institutional or computational resources.
+
+Place sponsor acknowledgments in the unnumbered footnote on the first page of the published version. In this draft pack, keep them here until you migrate to a publisher's class file at submission time.

package/template/packs/academic-paper/document/chapters/05-references/content/01-references.mdx

@@ -0,0 +1,27 @@
+## References
+
+Number citations consecutively within square brackets `[1]`. Sentence punctuation follows the bracket. Refer simply to the reference number, as in `[3]` — do not use `Ref. [3]` or `reference [3]` except at the start of a sentence: "Reference [3] was the first ...".
+
+Unless there are six authors or more, give all authors' names; do not use `et al.`. Papers not yet published should be cited as *unpublished*; accepted but not yet published as *in press*. Capitalize only the first word in a paper title, except for proper nouns and element symbols.
+
+For papers published in translation journals, give the English citation first, followed by the original foreign-language citation.
+
+---
+
+[1] G. Eason, B. Noble, and I. N. Sneddon, "On certain integrals of Lipschitz–Hankel type involving products of Bessel functions," *Phil. Trans. Roy. Soc. London*, vol. A247, pp. 529–551, April 1955.
+
+[2] J. Clerk Maxwell, *A Treatise on Electricity and Magnetism*, 3rd ed., vol. 2. Oxford: Clarendon, 1892, pp. 68–73.
+
+[3] I. S. Jacobs and C. P. Bean, "Fine particles, thin films and exchange anisotropy," in *Magnetism*, vol. III, G. T. Rado and H. Suhl, Eds. New York: Academic, 1963, pp. 271–350.
+
+[4] K. Elissa, "Title of paper if known," unpublished.
+
+[5] R. Nicole, "Title of paper with only first word capitalized," *J. Name Stand. Abbrev.*, in press.
+
+[6] Y. Yorozu, M. Hirano, K. Oka, and Y. Tagawa, "Electron spectroscopy studies on magneto-optical media and plastic substrate interface," *IEEE Transl. J. Magn. Japan*, vol. 2, pp. 740–741, August 1987.
+
+[7] M. Young, *The Technical Writer's Handbook*. Mill Valley, CA: University Science, 1989.
+
+---
+
+> **Reminder**: replace the seven placeholder references above with your own bibliography before circulating the draft. They are the IEEE conference template's example citations and have nothing to do with your paper.