@intentius/chant 0.1.11 → 0.1.13

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@intentius/chant",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
   "repository": {
     "type": "git",
-    "url": "https://github.com/intentius/chant.git",
+    "url": "https://github.com/INTENTIUS/chant.git",
     "directory": "packages/core"
   },
   "bugs": {
-    "url": "https://github.com/intentius/chant/issues"
+    "url": "https://github.com/INTENTIUS/chant/issues"
   },
   "keywords": [
     "infrastructure-as-code",

package/src/cli/commands/init.ts

@@ -33,6 +33,12 @@ export interface InitOptions {
   skipMcp?: boolean;
   /** Skip interactive install prompt */
   skipInstall?: boolean;
+  /**
+   * If set, install only the named skill (e.g. "chant-gitlab-migrate")
+   * rather than every skill the plugin exports. Useful for incremental
+   * skill installation without re-scaffolding the project.
+   */
+  skill?: string;
 }
 
 /**
@@ -442,18 +448,21 @@ export async function initCommand(options: InitOptions): Promise<InitResult> {
     );
   }
 
-  // Install skills from the lexicon's plugin
+  // Install skills from the lexicon's plugin. With --skill, install only
+  // the matching skill; without, install all.
   try {
     const plugin = await loadPlugin(options.lexicon);
     if (plugin.skills) {
-      const skills = plugin.skills();
-      if (skills.length > 0) {
-        for (const skill of skills) {
-          const skillDir = join(targetDir, "skills", skill.name);
-          mkdirSync(skillDir, { recursive: true });
-          writeFileSync(join(skillDir, "SKILL.md"), skill.content);
-          createdFiles.push(`skills/${skill.name}/SKILL.md`);
-        }
+      const all = plugin.skills();
+      const skills = options.skill ? all.filter((s) => s.name === options.skill) : all;
+      if (options.skill && skills.length === 0) {
+        warnings.push(`No skill named "${options.skill}" in lexicon ${options.lexicon}; nothing installed`);
+      }
+      for (const skill of skills) {
+        const skillDir = join(targetDir, "skills", skill.name);
+        mkdirSync(skillDir, { recursive: true });
+        writeFileSync(join(skillDir, "SKILL.md"), skill.content);
+        createdFiles.push(`skills/${skill.name}/SKILL.md`);
       }
     }
   } catch {

package/src/cli/commands/migrate.test.ts

@@ -0,0 +1,165 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, writeFileSync, rmSync, existsSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { migrateCommand } from "./migrate";
+import type { LexiconPlugin, MigrationResult } from "../../lexicon";
+
+function stubPlugin(behavior: Partial<{ supports: string[]; detect: boolean; result: MigrationResult }>): LexiconPlugin {
+  return {
+    name: "stub",
+    serializer: { name: "stub", rulePrefix: "STB", serialize: () => "" },
+    async generate() {},
+    async validate() {},
+    async coverage() {},
+    async package() {},
+    migrationSource(from: string) {
+      if (!(behavior.supports ?? ["github"]).includes(from)) return undefined;
+      return {
+        detect: () => behavior.detect ?? true,
+        async transform() {
+          return behavior.result ?? { output: "stub-output", provenance: [], diagnostics: [] };
+        },
+      };
+    },
+  };
+}
+
+describe("migrateCommand", () => {
+  let testDir: string;
+
+  beforeEach(() => {
+    testDir = mkdtempSync(join(tmpdir(), "chant-migrate-test-"));
+  });
+  afterEach(() => {
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  test("fails when target lexicon is not installed", async () => {
+    const file = join(testDir, "ci.yml");
+    writeFileSync(file, "jobs:\n  x:\n    runs-on: ubuntu-latest\n");
+    const r = await migrateCommand({
+      sourceFile: file, from: "github", to: "missing",
+      emit: "yaml", strict: false, validate: false, useComposites: false,
+      plugins: [],
+    });
+    expect(r.exitCode).toBe(1);
+    expect(r.error).toContain("not installed");
+  });
+
+  test("fails when target lexicon does not support migration", async () => {
+    const file = join(testDir, "ci.yml");
+    writeFileSync(file, "jobs:\n  x:\n    runs-on: ubuntu-latest\n");
+    const plugin: LexiconPlugin = {
+      name: "no-migrate",
+      serializer: { name: "no-migrate", rulePrefix: "NM", serialize: () => "" },
+      async generate() {},
+      async validate() {},
+      async coverage() {},
+      async package() {},
+    };
+    const r = await migrateCommand({
+      sourceFile: file, from: "github", to: "no-migrate",
+      emit: "yaml", strict: false, validate: false, useComposites: false,
+      plugins: [plugin],
+    });
+    expect(r.exitCode).toBe(1);
+    expect(r.error).toContain("does not support migration");
+  });
+
+  test("fails when source content is not recognised", async () => {
+    const file = join(testDir, "ci.yml");
+    writeFileSync(file, "not a workflow");
+    const r = await migrateCommand({
+      sourceFile: file, from: "github", to: "stub",
+      emit: "yaml", strict: false, validate: false, useComposites: false,
+      plugins: [stubPlugin({ detect: false })],
+    });
+    expect(r.exitCode).toBe(1);
+    expect(r.error).toContain("does not look like github");
+  });
+
+  test("writes output to --output file", async () => {
+    const file = join(testDir, "ci.yml");
+    const out = join(testDir, "out.yml");
+    writeFileSync(file, "jobs:\n  x:\n    runs-on: ubuntu-latest\n");
+    const r = await migrateCommand({
+      sourceFile: file, from: "github", to: "stub", output: out,
+      emit: "yaml", strict: false, validate: false, useComposites: false,
+      plugins: [stubPlugin({ result: { output: "hello-yaml\n", provenance: [], diagnostics: [] } })],
+    });
+    expect(r.exitCode).toBe(0);
+    expect(existsSync(out)).toBe(true);
+    expect(readFileSync(out, "utf-8")).toBe("hello-yaml\n");
+  });
+
+  test("--strict escalates error diagnostics to non-zero exit", async () => {
+    const file = join(testDir, "ci.yml");
+    writeFileSync(file, "jobs:\n  x:\n    runs-on: ubuntu-latest\n");
+    const r = await migrateCommand({
+      sourceFile: file, from: "github", to: "stub", output: join(testDir, "out.yml"),
+      emit: "yaml", strict: true, validate: false, useComposites: false,
+      plugins: [stubPlugin({
+        result: {
+          output: "out",
+          provenance: [],
+          diagnostics: [{ severity: "error", ruleId: "TEST-001", message: "bad", file: "<input>", line: 1, column: 1 }],
+        },
+      })],
+    });
+    expect(r.exitCode).toBe(1);
+  });
+
+  test("--report writes valid SARIF v2.1.0 JSON", async () => {
+    const file = join(testDir, "ci.yml");
+    const out = join(testDir, "out.yml");
+    const report = join(testDir, "r.sarif");
+    writeFileSync(file, "jobs:\n  x:\n    runs-on: ubuntu-latest\n");
+    await migrateCommand({
+      sourceFile: file, from: "github", to: "stub", output: out, reportFile: report,
+      emit: "yaml", strict: false, validate: false, useComposites: false,
+      plugins: [stubPlugin({
+        result: {
+          output: "out",
+          provenance: [],
+          diagnostics: [{ severity: "warning", ruleId: "TEST-W", message: "warn", file: "<in>", line: 2, column: 1 }],
+        },
+      })],
+    });
+    expect(existsSync(report)).toBe(true);
+    const sarif = JSON.parse(readFileSync(report, "utf-8"));
+    expect(sarif.version).toBe("2.1.0");
+    expect(sarif.runs?.[0]?.results?.length).toBe(1);
+    expect(sarif.runs[0].results[0].ruleId).toBe("TEST-W");
+  });
+
+  test("--strict off keeps exit 0 even with error diagnostics", async () => {
+    const file = join(testDir, "ci.yml");
+    writeFileSync(file, "jobs:\n  x:\n    runs-on: ubuntu-latest\n");
+    const r = await migrateCommand({
+      sourceFile: file, from: "github", to: "stub", output: join(testDir, "out.yml"),
+      emit: "yaml", strict: false, validate: false, useComposites: false,
+      plugins: [stubPlugin({
+        result: {
+          output: "out",
+          provenance: [],
+          diagnostics: [{ severity: "error", ruleId: "TEST-001", message: "bad", file: "<input>", line: 1, column: 1 }],
+        },
+      })],
+    });
+    expect(r.exitCode).toBe(0);
+  });
+});
+
+describe("tryValidateExternal", () => {
+  test("returns ran=false when neither glci nor glab is on PATH", async () => {
+    const { tryValidateExternal } = await import("./migrate");
+    const r = tryValidateExternal("stages:\n  - build\n");
+    if (!r.ran) {
+      expect(r.ok).toBe(false);
+      expect(r.backend).toBeUndefined();
+    } else {
+      expect(["glci", "glab"]).toContain(r.backend);
+    }
+  });
+});

package/src/cli/commands/migrate.ts

@@ -0,0 +1,469 @@
+/**
+ * `chant migrate` command implementation.
+ *
+ * Dispatches to the target lexicon's `migrationSource(from)` extension hook.
+ * The lexicon owns the actual translation logic; core orchestrates I/O,
+ * stdout/stderr surfaces, and exit codes.
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { formatError, formatInfo } from "../format";
+import { formatSarif } from "../reporters/stylish";
+import type { LexiconPlugin } from "../../lexicon";
+import type { LintRule, LintDiagnostic } from "../../lint/rule";
+
+export interface MigrateCliOpts {
+  sourceFile: string;
+  from: string;
+  to: string;
+  emit: "yaml" | "ts";
+  strict: boolean;
+  validate: boolean;
+  useComposites: boolean;
+  output?: string;
+  reportFile?: string;
+  plugins: LexiconPlugin[];
+}
+
+export interface MigrateCliResult {
+  exitCode: number;
+  /** Bytes written (output) if any */
+  output?: string;
+  /** All diagnostic records */
+  diagnostics: Array<Record<string, unknown>>;
+  /** Provenance records (used for SARIF + Markdown report) */
+  provenance: Array<Record<string, unknown>>;
+  /** Error message if dispatch failed */
+  error?: string;
+  /** Markdown summary lines printed to stderr */
+  markdownSummary?: string;
+}
+
+export async function migrateCommand(opts: MigrateCliOpts): Promise<MigrateCliResult> {
+  const targetPlugin = opts.plugins.find((p) => p.name === opts.to);
+  if (!targetPlugin) {
+    return {
+      exitCode: 1,
+      diagnostics: [],
+      provenance: [],
+      error: `Target lexicon "${opts.to}" is not installed`,
+    };
+  }
+  if (!targetPlugin.migrationSource) {
+    return {
+      exitCode: 1,
+      diagnostics: [],
+      provenance: [],
+      error: `Lexicon "${opts.to}" does not support migration`,
+    };
+  }
+  const source = targetPlugin.migrationSource(opts.from);
+  if (!source) {
+    return {
+      exitCode: 1,
+      diagnostics: [],
+      provenance: [],
+      error: `Lexicon "${opts.to}" does not support migration from "${opts.from}"`,
+    };
+  }
+
+  let content: string;
+  try {
+    content = readFileSync(opts.sourceFile, "utf-8");
+  } catch (err) {
+    return {
+      exitCode: 1,
+      diagnostics: [],
+      provenance: [],
+      error: `Cannot read ${opts.sourceFile}: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  if (!source.detect(content)) {
+    return {
+      exitCode: 1,
+      diagnostics: [],
+      provenance: [],
+      error: `Input file ${opts.sourceFile} does not look like ${opts.from} source`,
+    };
+  }
+
+  let result;
+  try {
+    result = await source.transform(content, {
+      emit: opts.emit,
+      useComposites: opts.useComposites,
+      sourceFile: opts.sourceFile,
+      strict: opts.strict,
+    });
+  } catch (err) {
+    return {
+      exitCode: 1,
+      diagnostics: [],
+      provenance: [],
+      error: `Transformation failed: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  // Write output (--output file or stdout)
+  if (opts.output && opts.output !== "-") {
+    try {
+      writeFileSync(opts.output, result.output);
+    } catch (err) {
+      return {
+        exitCode: 1,
+        diagnostics: result.diagnostics,
+        provenance: result.provenance,
+        error: `Cannot write ${opts.output}: ${err instanceof Error ? err.message : String(err)}`,
+      };
+    }
+  } else {
+    process.stdout.write(result.output);
+  }
+
+  // External validator (--validate) — glci preferred, glab fallback.
+  let validatorWarning: string | undefined;
+  if (opts.validate && opts.emit === "yaml") {
+    const v = tryValidateExternal(result.output);
+    if (!v.ran) {
+      validatorWarning = "neither glci nor glab is on PATH; skipping --validate";
+      if (opts.strict) {
+        return {
+          exitCode: 1,
+          output: result.output,
+          diagnostics: result.diagnostics,
+          provenance: result.provenance,
+          error: "--strict --validate: neither glci nor glab is on PATH",
+        };
+      }
+    } else if (!v.ok) {
+      console.error(`Validator (${v.backend}) reported errors:\n${v.output}`);
+      if (opts.strict) {
+        return {
+          exitCode: 1,
+          output: result.output,
+          diagnostics: result.diagnostics,
+          provenance: result.provenance,
+          error: `--strict: ${v.backend} validation failed`,
+        };
+      }
+    } else {
+      console.error(`Validator (${v.backend}) OK`);
+    }
+  }
+
+  // SARIF report (--report <path>) — reuse the lint-side formatSarif so any
+  // CI SARIF ingest path treats migration findings uniformly.
+  if (opts.reportFile) {
+    try {
+      const rules = await loadMigrationRules(opts.to);
+      const lintShape = result.diagnostics as unknown as LintDiagnostic[];
+      const sarif = formatSarif(lintShape, rules);
+      writeFileSync(opts.reportFile, sarif);
+    } catch (err) {
+      // Non-fatal: surface the failure but don't abort the migration
+      console.error(`Warning: could not write SARIF report to ${opts.reportFile}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  // Markdown summary (always to stderr — leaves stdout clean for piping)
+  const markdownSummary = formatMarkdownSummary(result.provenance, result.diagnostics, content);
+
+  // Determine exit code: any error-severity diagnostic fails when --strict.
+  // The transformer already escalates needs-review → error when opts.strict
+  // is passed via MigrationSource.transform(); we double-check here.
+  const errorDiagnostics = result.diagnostics.filter((d) => d.severity === "error");
+  const exitCode = opts.strict && errorDiagnostics.length > 0 ? 1 : 0;
+
+  return {
+    exitCode,
+    output: result.output,
+    diagnostics: result.diagnostics,
+    provenance: result.provenance,
+    markdownSummary,
+  };
+}
+
+interface ValidatorResult {
+  ran: boolean;
+  ok: boolean;
+  backend?: "glci" | "glab";
+  output: string;
+}
+
+function isOnPath(cmd: string): boolean {
+  // Use the OS-native lookup. `which` exists on macOS/Linux; `where` on Windows.
+  const lookup = process.platform === "win32" ? "where" : "which";
+  const r = spawnSync(lookup, [cmd], { encoding: "utf-8" });
+  return r.status === 0;
+}
+
+/**
+ * Run glci or glab against the generated .gitlab-ci.yml. Prefers glci
+ * (offline, no auth). Falls back to glab ci lint. Returns a structured
+ * result so the caller can decide how to surface success/failure.
+ *
+ * Exported for testability.
+ */
+export function tryValidateExternal(yamlText: string): ValidatorResult {
+  if (isOnPath("glci")) {
+    const r = spawnSync("glci", ["lint", "-f", "-"], { input: yamlText, encoding: "utf-8" });
+    return { ran: true, ok: r.status === 0, backend: "glci", output: (r.stdout ?? "") + (r.stderr ?? "") };
+  }
+  if (isOnPath("glab")) {
+    const r = spawnSync("glab", ["ci", "lint", "-f", "-"], { input: yamlText, encoding: "utf-8" });
+    return { ran: true, ok: r.status === 0, backend: "glab", output: (r.stdout ?? "") + (r.stderr ?? "") };
+  }
+  return { ran: false, ok: false, output: "" };
+}
+
+/**
+ * Lazily load the target lexicon's MIGRATION_RULES (used for SARIF enrichment).
+ * Returns an empty array if the lexicon doesn't expose them.
+ */
+async function loadMigrationRules(targetLexicon: string): Promise<LintRule[]> {
+  // For now only gitlab exposes migration rules. Hard-coded import keeps
+  // the dependency direction explicit; widen the switch when more
+  // lexicons ship their own migrate paths.
+  if (targetLexicon === "gitlab") {
+    try {
+      const mod = await import("@intentius/chant-lexicon-gitlab/migrate/from-github/rules");
+      return (mod as { MIGRATION_RULES: LintRule[] }).MIGRATION_RULES;
+    } catch {
+      return [];
+    }
+  }
+  return [];
+}
+
+/**
+ * Format the migration report as Markdown, mirroring the output format
+ * prescribed by the upstream gitlab-org/ci-cd/github-actions-to-gitlab-ci
+ * skill: overview, classification, diagnostic table, aggregated manual
+ * setup steps, suggested GitLab improvements, honest caveats.
+ *
+ * The same data backs the SARIF report (via formatSarif); this is the
+ * human-readable surface.
+ */
+function formatMarkdownSummary(
+  provenance: Array<Record<string, unknown>>,
+  diagnostics: Array<Record<string, unknown>>,
+  sourceContent?: string,
+): string {
+  const totals = { error: 0, warning: 0, info: 0 };
+  for (const d of diagnostics) {
+    const sev = d.severity as string;
+    if (sev === "error" || sev === "warning" || sev === "info") {
+      totals[sev]++;
+    }
+  }
+
+  // Derive workflow shape from source (best effort) for the overview line
+  const overview = deriveOverview(sourceContent);
+  const classification = classifyWorkflow(sourceContent);
+  const manualSteps = collectManualSetupSteps(diagnostics);
+  const suggestions = collectSuggestions(provenance, sourceContent);
+
+  const lines: string[] = [];
+  lines.push("");
+  lines.push("## Migration report");
+  lines.push("");
+  if (overview) lines.push(`**Overview** — ${overview}`);
+  if (classification) {
+    lines.push("");
+    lines.push(classification);
+  }
+  lines.push("");
+  lines.push(`- Provenance records: ${provenance.length}`);
+  lines.push(`- Diagnostics: ${totals.error} error, ${totals.warning} warning, ${totals.info} info`);
+
+  if (diagnostics.length > 0) {
+    lines.push("");
+    lines.push("### Diagnostics");
+    lines.push("");
+    lines.push("| Severity | Rule | Message |");
+    lines.push("|---|---|---|");
+    for (const d of diagnostics.slice(0, 50)) {
+      lines.push(`| ${d.severity} | ${d.ruleId} | ${String(d.message).slice(0, 120)} |`);
+    }
+    if (diagnostics.length > 50) {
+      lines.push(`| … | … | ${diagnostics.length - 50} more diagnostics omitted |`);
+    }
+  }
+
+  if (manualSteps.length > 0) {
+    lines.push("");
+    lines.push("### Manual setup steps");
+    lines.push("");
+    for (let i = 0; i < manualSteps.length; i++) {
+      lines.push(`${i + 1}. ${manualSteps[i]}`);
+    }
+  }
+
+  if (suggestions.length > 0) {
+    lines.push("");
+    lines.push("### Suggested GitLab improvements");
+    lines.push("");
+    for (const s of suggestions) lines.push(`- ${s}`);
+  }
+
+  if (totals.error > 0 || totals.warning > 0) {
+    lines.push("");
+    lines.push("### Honest caveats");
+    lines.push("");
+    lines.push(`The translation has ${totals.error} item${totals.error === 1 ? "" : "s"} needing review and ${totals.warning} approximation${totals.warning === 1 ? "" : "s"}. Review the diagnostics above before pushing the generated YAML.`);
+  }
+
+  return lines.join("\n");
+}
+
+/** Derive a one-sentence overview from the source workflow shape. */
+function deriveOverview(content?: string): string | undefined {
+  if (!content) return undefined;
+  const nameMatch = /^\s*name\s*:\s*(.+?)\s*$/m.exec(content);
+  const name = nameMatch ? nameMatch[1].replace(/['"]/g, "") : undefined;
+  const jobCount = countJobs(content);
+  const triggers = (content.match(/^\s*on\s*:/gm) ?? []).length > 0;
+  const parts: string[] = [];
+  if (name) parts.push(`workflow "${name}"`);
+  if (jobCount > 0) parts.push(`${jobCount} job${jobCount === 1 ? "" : "s"}`);
+  if (triggers) parts.push("triggered via on:");
+  if (parts.length === 0) return undefined;
+  return parts.join(", ") + ".";
+}
+
+/** Count top-level entries directly under `jobs:`. */
+function countJobs(content: string): number {
+  // Find the jobs: line, then walk forward collecting indented-2 keys until
+  // we hit a non-indented non-empty line (next top-level key) or EOF.
+  const lines = content.split(/\r?\n/);
+  let inJobs = false;
+  let count = 0;
+  for (const line of lines) {
+    if (/^\s*jobs\s*:\s*$/.test(line)) {
+      inJobs = true;
+      continue;
+    }
+    if (!inJobs) continue;
+    if (/^\S/.test(line)) break; // next top-level key
+    if (/^\s{2}[A-Za-z_][A-Za-z0-9_-]*\s*:\s*$/.test(line)) {
+      count++;
+    }
+  }
+  return count;
+}
+
+/**
+ * Detect workflows whose triggers are predominantly repo-automation
+ * events (issues, labels, comments, discussions) — GitLab CI can't replace
+ * these because pipelines only run on git events.
+ */
+function classifyWorkflow(content?: string): string | undefined {
+  if (!content) return undefined;
+  const onBlockMatch = /^\s*on\s*:([\s\S]*?)(?=^\S|\Z)/m.exec(content);
+  if (!onBlockMatch) return undefined;
+  const onText = onBlockMatch[1];
+  const automationEvents = [
+    "issues", "issue_comment", "pull_request_review", "pull_request_review_comment",
+    "discussion", "discussion_comment", "label", "milestone", "project_card",
+    "release", "star", "watch", "fork", "create", "delete",
+  ];
+  const found = automationEvents.filter((e) =>
+    new RegExp(`^\\s*${e}\\s*:`, "m").test(onText),
+  );
+  const gitEvents = ["push", "pull_request", "schedule", "workflow_dispatch", "workflow_call", "tag"];
+  const foundGit = gitEvents.filter((e) =>
+    new RegExp(`^\\s*${e}\\s*:|${e}\\b`, "m").test(onText),
+  );
+  if (found.length > 0 && foundGit.length === 0) {
+    return `> ⚠️ **Repo-automation workflow detected** (triggers: ${found.join(", ")}). GitLab CI/CD only runs on git events; consider [gitlab-triage](https://gitlab.com/gitlab-org/ruby/gems/gitlab-triage) on a schedule, or webhooks + an external service. The translated YAML below is best-effort.`;
+  }
+  if (found.length > 0 && foundGit.length > 0) {
+    return `> ℹ️ Mixed triggers: git (${foundGit.join(", ")}) + automation (${found.join(", ")}). The automation events have no GitLab equivalent; the translated pipeline only fires on the git events.`;
+  }
+  return undefined;
+}
+
+/** Aggregate the human-actionable manual setup steps from needs-review diagnostics. */
+function collectManualSetupSteps(diagnostics: Array<Record<string, unknown>>): string[] {
+  const seen = new Set<string>();
+  const steps: string[] = [];
+  for (const d of diagnostics) {
+    if (d.severity !== "warning" && d.severity !== "error") continue;
+    const ruleId = d.ruleId as string;
+    const action = manualStepFor(ruleId);
+    if (action && !seen.has(action)) {
+      seen.add(action);
+      steps.push(action);
+    }
+  }
+  return steps;
+}
+
+const MANUAL_STEPS_BY_RULE: Record<string, string> = {
+  "MIG-PERMISSIONS-001": "Configure CI/CD token access at Project Settings > CI/CD > Token Access (no per-job YAML equivalent in GitLab).",
+  "MIG-ON-SCHEDULE": "Create a pipeline schedule at Project Settings > CI/CD > Schedules (cron lives in the GitLab UI, not in YAML).",
+  "MIG-ON-DISPATCH": "Convert `workflow_dispatch.inputs` to `spec:inputs` at the top of the generated YAML (GitLab 17+). Every input must have a default so auto-triggered pipelines don't fail.",
+  "MIG-ON-NON-GIT": "Replace issue/MR/discussion triggers with gitlab-triage on a schedule, or webhooks + an external service. GitLab CI/CD only runs on git events.",
+  "MIG-NEEDS-OUTPUTS-001": "Convert step/job outputs to the `artifacts:reports:dotenv` pattern in the producing job, and add `needs: [{ job: X, artifacts: true }]` in the consuming job.",
+  "MIG-JOB-OUTPUTS": "Replace GitHub job outputs with `artifacts:reports:dotenv` files written by the producing job.",
+  "MIG-MATRIX-INCLUDE-001": "Manually unroll `matrix.include`/`matrix.exclude` entries; GitLab `parallel:matrix:` doesn't support these directly.",
+  "MIG-FAIL-FAST": "GitLab's `parallel:matrix:` doesn't fail-fast by default. If fail-fast is critical, wrap the matrix in a job that exits on first child failure.",
+  "MIG-RUNS-ON-NON-LINUX": "Register a self-hosted GitLab runner with the appropriate `tags:` for macOS or Windows jobs.",
+  "MIG-REUSABLE-WORKFLOW": "Rewrite `uses: org/repo/.github/workflows/*.yml` calls as GitLab `include:project:` + `variables:` parameterisation. Typed inputs aren't supported; document expected variable names.",
+};
+
+function manualStepFor(ruleId: string): string | undefined {
+  return MANUAL_STEPS_BY_RULE[ruleId];
+}
+
+/** Suggest GitLab-native improvements based on workflow shape + provenance. */
+function collectSuggestions(
+  provenance: Array<Record<string, unknown>>,
+  content?: string,
+): string[] {
+  const out: string[] = [];
+  // DAG (needs:) is already passed through; suggest it if multiple jobs exist without explicit needs
+  const hasNeeds = provenance.some((p) => p.rule === "MIG-NEEDS");
+  const jobCount = content ? countJobs(content) : 0;
+  if (jobCount >= 3 && !hasNeeds) {
+    out.push("**DAG with `needs:`** — your jobs run sequentially via stage barriers. Adding explicit `needs:` lets jobs run as soon as their dependencies finish, often cutting pipeline time significantly.");
+  }
+  // rules:changes: when the workflow looks like it might benefit from path filtering
+  if (content && /paths\s*:/m.test(content)) {
+    out.push("**`rules:changes:`** — GitLab supports path-based job filtering natively. Convert GitHub `on:push:paths:` to `rules:changes:` on each job for monorepo-friendly conditional execution.");
+  }
+  // include: for multi-file workflow repos
+  if (content && /\buses\s*:\s*\.\/.+\.ya?ml/m.test(content)) {
+    out.push("**`include:`** — your workflow references local reusable workflows. GitLab `include:local:` merges YAML at parse time; consider migrating those references too.");
+  }
+  // Composite-recogniser hint when --use-composites would simplify
+  if (content && /actions\/setup-node/.test(content) && jobCount >= 1) {
+    out.push("**`--use-composites`** — re-run with this flag to collapse Node-shaped pipelines into a single `NodePipeline({...})` call (5–10× shorter generated TypeScript).");
+  }
+  // resource_group / interruptible already mapped; suggest protected environments for deploy jobs
+  if (content && /\bdeploy\b/i.test(content)) {
+    out.push("**Protected environments** — gate deploy jobs by approval rules and environment-specific variables (Project Settings > CI/CD > Environments). No GitHub equivalent.");
+  }
+  // GitLab CI templates
+  if (content && /security|sast|dast|terraform/i.test(content)) {
+    out.push("**GitLab CI templates** — `include:template:` gives you Auto DevOps, SAST, DAST, Container Scanning, Terraform, etc. out of the box. No GitHub Actions equivalent.");
+  }
+  return out;
+}
+
+export function printMigrateResult(result: MigrateCliResult): void {
+  if (result.error) {
+    console.error(formatError({ message: result.error }));
+    return;
+  }
+  if (result.markdownSummary) {
+    console.error(result.markdownSummary);
+  }
+  if (result.exitCode === 0) {
+    console.error(formatInfo("\nMigration complete."));
+  } else {
+    console.error(formatError({ message: "Migration completed with errors (--strict)" }));
+  }
+}

package/src/cli/handlers/init.ts

@@ -17,6 +17,7 @@ export async function runInit(ctx: CommandContext): Promise<number> {
     path: args.path === "." ? undefined : args.path,
     lexicon: args.lexicon,
     template: args.template,
+    skill: args.skill,
     force: args.force,
     skipInstall: true,
   });

package/src/cli/handlers/migrate.ts

@@ -0,0 +1,54 @@
+import { migrateCommand, printMigrateResult } from "../commands/migrate";
+import { formatError } from "../format";
+import { loadPlugins } from "../plugins";
+import type { CommandContext } from "../registry";
+
+export async function runMigrate(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+
+  // The migrate path is the second positional (args.path); `chant migrate <file>`
+  // populates args.path with the file path. Default is current directory.
+  if (!args.path || args.path === ".") {
+    console.error(formatError({
+      message: "chant migrate requires a source file path",
+      hint: "chant migrate .github/workflows/ci.yml --output .gitlab-ci.yml",
+    }));
+    return 1;
+  }
+
+  // migrate does not require a chant project context. Load the target
+  // lexicon directly by name.
+  const toName = args.migrateTo ?? "gitlab";
+  let plugins;
+  try {
+    plugins = await loadPlugins([toName]);
+  } catch (err) {
+    console.error(formatError({
+      message: `Cannot load target lexicon "${toName}": ${err instanceof Error ? err.message : String(err)}`,
+      hint: `Install @intentius/chant-lexicon-${toName} or pass --to <other-lexicon>`,
+    }));
+    return 1;
+  }
+
+  const emit = (args.emit as "yaml" | "ts" | undefined) ?? "yaml";
+  if (emit !== "yaml" && emit !== "ts") {
+    console.error(formatError({ message: `Invalid --emit value: ${emit}. Expected 'yaml' or 'ts'.` }));
+    return 1;
+  }
+
+  const result = await migrateCommand({
+    sourceFile: args.path,
+    from: args.migrateFrom ?? "github",
+    to: args.migrateTo ?? "gitlab",
+    emit,
+    strict: args.strict ?? false,
+    validate: args.validate ?? false,
+    useComposites: args.useComposites ?? false,
+    output: args.output,
+    reportFile: args.reportFile,
+    plugins,
+  });
+
+  printMigrateResult(result);
+  return result.exitCode;
+}

package/src/cli/main.ts

@@ -12,6 +12,7 @@ import { runDevGenerate, runDevPublish, runDevOnboard, runDevCheckLexicon, runDe
 import { runServeLsp, runServeMcp, runServeUnknown } from "./handlers/serve";
 import { runInit, runInitLexicon } from "./handlers/init";
 import { runList, runImport, runUpdate, runDoctor } from "./handlers/misc";
+import { runMigrate } from "./handlers/migrate";
 import { runStateSnapshot, runStateShow, runStateDiff, runStateLog, runStateUnknown } from "./handlers/state";
 import { runGraph } from "./handlers/graph";
 import { runOp, runOpList, runOpStatus, runOpSignal, runOpCancel, runOpLog } from "./handlers/run";
@@ -37,6 +38,14 @@ export function parseArgs(args: string[]): ParsedArgs {
     profile: undefined,
     report: undefined,
     live: false,
+    migrateFrom: undefined,
+    migrateTo: undefined,
+    emit: undefined,
+    strict: false,
+    validate: false,
+    useComposites: false,
+    reportFile: undefined,
+    skill: undefined,
   };
 
   let i = 0;
@@ -64,9 +73,31 @@ export function parseArgs(args: string[]): ParsedArgs {
     } else if (arg === "--profile" || arg === "-p") {
       result.profile = args[++i];
     } else if (arg === "--report") {
-      result.report = true;
+      // --report alone is the boolean (used by `run`); --report <path> is
+      // the migrate-command file path. Look ahead for a non-flag.
+      const next = args[i + 1];
+      if (next && !next.startsWith("-")) {
+        result.reportFile = next;
+        i++;
+      } else {
+        result.report = true;
+      }
     } else if (arg === "--live") {
       result.live = true;
+    } else if (arg === "--from") {
+      result.migrateFrom = args[++i];
+    } else if (arg === "--to") {
+      result.migrateTo = args[++i];
+    } else if (arg === "--emit") {
+      result.emit = args[++i];
+    } else if (arg === "--strict") {
+      result.strict = true;
+    } else if (arg === "--validate") {
+      result.validate = true;
+    } else if (arg === "--use-composites") {
+      result.useComposites = true;
+    } else if (arg === "--skill") {
+      result.skill = args[++i];
     } else if (!arg.startsWith("-")) {
       if (!result.command) {
         result.command = arg;
@@ -102,6 +133,8 @@ Commands:
   lint                  Check specifications for issues
   list                  List discovered entities
   import                Import external template into TypeScript
+  migrate <file>        Translate a workflow between lexicons
+                        (default: --from github --to gitlab)
 
 Ops:
   run <name>            Start an Op workflow (spawns worker + submits to Temporal)
@@ -142,6 +175,7 @@ Options:
                         - lint: stylish (default), json, or sarif
   -d, --lexicon <name>  Build only the specified lexicon (e.g. aws, gitlab)
   -t, --template <name> Init template (e.g. node-pipeline, docker-build)
+  --skill <name>        Init: install only this skill from the lexicon
   --fix                 Auto-fix fixable issues (lint command)
   --force               Force overwrite existing files (import command)
   -w, --watch           Watch for changes and rebuild/re-lint (build, lint)
@@ -149,6 +183,13 @@ Options:
   -h, --help            Show this help message
   -p, --profile <name>  Temporal worker profile to use (run command)
   --report              Print deployment report instead of running (run command)
+                        OR with a path arg: SARIF report destination (migrate)
+  --from <name>         Source lexicon for migrate (default: github)
+  --to <name>           Target lexicon for migrate (default: gitlab)
+  --emit <fmt>          Migration output format: yaml (default) or ts
+  --strict              Escalate needs-review/validation to errors (migrate)
+  --validate            Run external validator (glci/glab) after migrate
+  --use-composites      Rewrite to composite calls when patterns match (migrate)
 
 Examples:
   chant build ./infra/
@@ -197,6 +238,7 @@ const registry: CommandDef[] = [
   { name: "lint", handler: runLint },
   { name: "list", handler: runList },
   { name: "import", handler: runImport },
+  { name: "migrate", handler: runMigrate },
   { name: "init", handler: runInit },
   { name: "init lexicon", handler: runInitLexicon },
 { name: "update", handler: runUpdate },

package/src/cli/registry.ts

@@ -21,6 +21,22 @@ export interface ParsedArgs {
   profile?: string;
   report?: boolean;
   live: boolean;
+  /** `chant migrate --from <name>` (default "github") */
+  migrateFrom?: string;
+  /** `chant migrate --to <name>` (default "gitlab") */
+  migrateTo?: string;
+  /** `chant migrate --emit yaml|ts` */
+  emit?: string;
+  /** Escalate needs-review diagnostics to errors (migrate command) */
+  strict?: boolean;
+  /** Run glci/glab after emit (migrate command) */
+  validate?: boolean;
+  /** Recognise composite patterns in output (migrate command) */
+  useComposites?: boolean;
+  /** Write SARIF report to this path (migrate command); distinct from boolean --report */
+  reportFile?: string;
+  /** `chant init --skill <name>` filter (added in #95 commit) */
+  skill?: string;
 }
 
 /**

package/src/cli/reporters/stylish.ts

@@ -215,7 +215,7 @@ export function formatSarif(
           driver: {
             name: "chant",
             version: version ?? "0.1.0",
-            informationUri: "https://chant.dev",
+            informationUri: "https://intentius.io/chant",
             rules: sarifRules,
           },
         },
@@ -267,7 +267,7 @@ function buildRuleMetadata(
       id,
       shortDescription: { text: descText },
       fullDescription: { text: descText },
-      helpUri: rule?.helpUri || `https://chant.dev/lint-rules/${id.toLowerCase()}`,
+      helpUri: rule?.helpUri || `https://intentius.io/chant/lint-rules/${id.toLowerCase()}`,
       defaultConfiguration: {
         level: mapSeverity(rule?.severity ?? "warning"),
       },

package/src/codegen/docs-sections.ts

@@ -150,7 +150,7 @@ export function generateSerialization(config: DocsConfig): string {
     lines.push(
       `The ${config.displayName} lexicon serializes resources into its native output format during the build step.`,
       "",
-      "See the [Serialization](/serialization/output-formats) guide for general information about output formats in chant.",
+      "See the [Serialization](/chant/serialization/output-formats) guide for general information about output formats in chant.",
     );
   }
 

package/src/codegen/docs.ts

@@ -7,8 +7,9 @@
  * (service grouping, resource type URLs, custom overview content).
  */
 
-import { readFileSync, writeFileSync, mkdirSync, rmSync } from "fs";
+import { copyFileSync, readFileSync, writeFileSync, mkdirSync, rmSync } from "fs";
 import { join } from "path";
+import { fileURLToPath } from "url";
 
 import { expandFileMarkers } from "./docs-file-markers";
 import { scanRules, generateRules } from "./docs-rule-scanning";
@@ -222,14 +223,25 @@ export const collections = {
 `,
   );
 
+  // src/rehype-base-url.mjs — copied from chant core so Astro can import it
+  // without the generated docs site needing a workspace dep on @intentius/chant.
+  const pluginSrcPath = fileURLToPath(
+    new URL("./rehype-base-url.mjs", import.meta.url),
+  );
+  copyFileSync(pluginSrcPath, join(outDir, "src", "rehype-base-url.mjs"));
+
   // astro.config.mjs
+  const rehypeLine = config.basePath
+    ? `\n  markdown: {\n    rehypePlugins: [[rehypeBaseUrl, { base: '${config.basePath}', projectBase: '/chant' }]],\n  },`
+    : "";
   writeFileSync(
     join(outDir, "astro.config.mjs"),
     `// @ts-check
 import { defineConfig } from 'astro/config';
 import starlight from '@astrojs/starlight';
+import rehypeBaseUrl from './src/rehype-base-url.mjs';
 
-export default defineConfig({${config.basePath ? `\n  base: '${config.basePath}',` : ""}
+export default defineConfig({${config.basePath ? `\n  base: '${config.basePath}',` : ""}${rehypeLine}
   integrations: [
     starlight({
       title: '${config.displayName}',

package/src/codegen/rehype-base-url.d.mts

@@ -0,0 +1,17 @@
+export interface RehypeBaseUrlOptions {
+  /** Site base, e.g. "/chant" or "/chant/lexicons/aws". Trailing/leading slashes optional. */
+  base: string;
+  /** Project-wide base used to detect already-correctly-prefixed cross-site links. */
+  projectBase?: string;
+}
+
+type HastNode = {
+  type: string;
+  tagName?: string;
+  properties?: Record<string, unknown>;
+  children?: HastNode[];
+};
+
+export default function rehypeBaseUrl(
+  opts: RehypeBaseUrlOptions,
+): (tree: HastNode) => void;

package/src/codegen/rehype-base-url.mjs

@@ -0,0 +1,68 @@
+/**
+ * Rehype plugin: prepend a configured `base` to root-relative `<a href>` attributes.
+ *
+ * Astro/Starlight only base-prefixes its own internal navigation (sidebar `link:`
+ * entries, `slug:` entries). Root-relative links written in MD/MDX content body
+ * — e.g. `[AWS](/lexicons/aws/)` — are emitted verbatim and 404 in production
+ * when the site is served from a non-root `base`.
+ *
+ * This plugin walks the HAST tree, finds `<a>` elements whose href starts with
+ * `/` (single leading slash, not `//`), and prepends the site's `base`. It
+ * idempotently skips hrefs that already start with the site's own base or the
+ * project-wide base.
+ *
+ * @typedef {Object} RehypeBaseUrlOptions
+ * @property {string} base - Site base, e.g. "/chant" or "/chant/lexicons/aws". Trailing/leading slashes optional.
+ * @property {string} [projectBase] - Project-wide base used to detect already-correctly-prefixed cross-site links.
+ */
+
+const PROTOCOL_RE = /^[a-z][a-z0-9+.-]*:/i;
+
+function normalizeBase(value) {
+  return "/" + value.replace(/^\/+|\/+$/g, "");
+}
+
+/**
+ * @param {RehypeBaseUrlOptions} opts
+ */
+export default function rehypeBaseUrl(opts) {
+  const base = normalizeBase(opts.base);
+  if (base === "/") {
+    return () => {};
+  }
+  const ownPrefix = base + "/";
+  const projectPrefix = opts.projectBase
+    ? normalizeBase(opts.projectBase) + "/"
+    : null;
+
+  function rewrite(node) {
+    if (
+      node &&
+      node.type === "element" &&
+      node.tagName === "a" &&
+      node.properties &&
+      typeof node.properties.href === "string"
+    ) {
+      const href = node.properties.href;
+      if (
+        href.length > 0 &&
+        !href.startsWith("//") &&
+        !PROTOCOL_RE.test(href) &&
+        !href.startsWith("#") &&
+        href.startsWith("/") &&
+        href !== base &&
+        !href.startsWith(ownPrefix) &&
+        !(projectPrefix && href.startsWith(projectPrefix))
+      ) {
+        node.properties.href = base + href;
+      }
+    }
+    if (node && node.children) {
+      for (const child of node.children) rewrite(child);
+    }
+  }
+
+  return (tree) => {
+    rewrite(tree);
+  };
+}

package/src/codegen/rehype-base-url.test.ts

@@ -0,0 +1,161 @@
+import { describe, it, expect } from "vitest";
+import rehypeBaseUrl from "./rehype-base-url.mjs";
+
+type Element = {
+  type: "element";
+  tagName: string;
+  properties: Record<string, unknown>;
+  children: Element[];
+};
+
+function a(href: string): Element {
+  return { type: "element", tagName: "a", properties: { href }, children: [] };
+}
+
+function tree(...links: Element[]): Element {
+  return { type: "element", tagName: "root", properties: {}, children: links };
+}
+
+function run(opts: { base: string; projectBase?: string }, href: string): string {
+  const plugin = rehypeBaseUrl(opts);
+  const root = tree(a(href));
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  (plugin as any)(root);
+  return root.children[0].properties.href as string;
+}
+
+describe("rehypeBaseUrl — main docs (base=/chant)", () => {
+  const opts = { base: "/chant", projectBase: "/chant" };
+
+  it("prepends base to plain root-relative link", () => {
+    expect(run(opts, "/lexicons/aws/")).toBe("/chant/lexicons/aws/");
+  });
+
+  it("prepends base to /api/* TypeDoc link", () => {
+    expect(run(opts, "/api/classes/attrref/")).toBe("/chant/api/classes/attrref/");
+  });
+
+  it("leaves already-prefixed /chant/ link unchanged", () => {
+    expect(run(opts, "/chant/concepts/philosophy/")).toBe(
+      "/chant/concepts/philosophy/",
+    );
+  });
+
+  it("leaves the bare base unchanged", () => {
+    expect(run(opts, "/chant")).toBe("/chant");
+  });
+
+  it("leaves https://… unchanged", () => {
+    expect(run(opts, "https://example.com/foo")).toBe("https://example.com/foo");
+  });
+
+  it("leaves protocol-relative // unchanged", () => {
+    expect(run(opts, "//cdn.example.com/x")).toBe("//cdn.example.com/x");
+  });
+
+  it("leaves mailto: unchanged", () => {
+    expect(run(opts, "mailto:a@b")).toBe("mailto:a@b");
+  });
+
+  it("leaves anchor #foo unchanged", () => {
+    expect(run(opts, "#section")).toBe("#section");
+  });
+
+  it("leaves relative path unchanged", () => {
+    expect(run(opts, "foo/bar")).toBe("foo/bar");
+  });
+
+  it("leaves dot-relative path unchanged", () => {
+    expect(run(opts, "../sibling/")).toBe("../sibling/");
+  });
+
+  it("leaves empty href unchanged", () => {
+    expect(run(opts, "")).toBe("");
+  });
+});
+
+describe("rehypeBaseUrl — lexicon (base=/chant/lexicons/aws, projectBase=/chant)", () => {
+  const opts = { base: "/chant/lexicons/aws", projectBase: "/chant" };
+
+  it("leaves cross-site /chant/… unchanged (projectBase guard)", () => {
+    expect(run(opts, "/chant/concepts/philosophy/")).toBe(
+      "/chant/concepts/philosophy/",
+    );
+  });
+
+  it("leaves cross-lexicon /chant/lexicons/k8s/… unchanged", () => {
+    expect(run(opts, "/chant/lexicons/k8s/")).toBe("/chant/lexicons/k8s/");
+  });
+
+  it("leaves the lexicon's own base prefix unchanged", () => {
+    expect(run(opts, "/chant/lexicons/aws/composites/")).toBe(
+      "/chant/lexicons/aws/composites/",
+    );
+  });
+
+  it("prepends lexicon base to bare /foo/ (interpreted as site-local)", () => {
+    expect(run(opts, "/foo/bar/")).toBe("/chant/lexicons/aws/foo/bar/");
+  });
+});
+
+describe("rehypeBaseUrl — base normalization", () => {
+  it("is a no-op when base is '/'", () => {
+    const plugin = rehypeBaseUrl({ base: "/" });
+    const root = tree(a("/foo"));
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (plugin as any)(root);
+    expect(root.children[0].properties.href).toBe("/foo");
+  });
+
+  it("handles trailing slashes in base option", () => {
+    expect(run({ base: "/chant/", projectBase: "/chant/" }, "/foo")).toBe(
+      "/chant/foo",
+    );
+  });
+
+  it("handles missing leading slash in base option", () => {
+    expect(run({ base: "chant", projectBase: "chant" }, "/foo")).toBe("/chant/foo");
+  });
+});
+
+describe("rehypeBaseUrl — tree traversal", () => {
+  it("rewrites nested <a> hrefs", () => {
+    const plugin = rehypeBaseUrl({ base: "/chant", projectBase: "/chant" });
+    const root = tree();
+    root.children = [
+      {
+        type: "element",
+        tagName: "div",
+        properties: {},
+        children: [a("/foo"), a("/bar")],
+      },
+      a("/baz"),
+    ];
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (plugin as any)(root);
+    const div = root.children[0] as Element;
+    expect(div.children[0].properties.href).toBe("/chant/foo");
+    expect(div.children[1].properties.href).toBe("/chant/bar");
+    expect(root.children[1].properties.href).toBe("/chant/baz");
+  });
+
+  it("leaves non-<a> elements alone", () => {
+    const plugin = rehypeBaseUrl({ base: "/chant" });
+    const root: Element = {
+      type: "element",
+      tagName: "root",
+      properties: {},
+      children: [
+        {
+          type: "element",
+          tagName: "img",
+          properties: { src: "/foo.png" },
+          children: [],
+        },
+      ],
+    };
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (plugin as any)(root);
+    expect(root.children[0].properties.src).toBe("/foo.png");
+  });
+});

package/src/lexicon.ts

@@ -97,6 +97,47 @@ export interface IntrinsicDef {
   readonly isTag?: boolean;
 }
 
+/**
+ * Options passed to a MigrationSource by `chant migrate`.
+ */
+export interface MigrateOptions {
+  /** Output format. */
+  emit?: "yaml" | "ts";
+  /** Recognise composite patterns when emitting. */
+  useComposites?: boolean;
+  /** Source file path (for provenance display only). */
+  sourceFile?: string;
+  /** Escalate needs-review diagnostics to errors. */
+  strict?: boolean;
+}
+
+/**
+ * Result of `MigrationSource.transform()`.
+ *
+ * Provenance is a generic side channel: each record is `{ sourceKey, rule,
+ * category, note?, ... }`. Diagnostics are SARIF-compatible records derived
+ * from provenance (concrete shape lives in `packages/core/src/lint/rule.ts`).
+ */
+export interface MigrationResult {
+  /** Rendered output (YAML by default, TS when emit: "ts"). */
+  output: string;
+  /** Per-key provenance records (typed loosely at the core level). */
+  provenance: Array<Record<string, unknown>>;
+  /** SARIF-shaped diagnostics. */
+  diagnostics: Array<Record<string, unknown>>;
+}
+
+/**
+ * Edge that translates one lexicon's source format into this lexicon's IR
+ * and output. Exposed via `LexiconPlugin.migrationSource(from)`.
+ */
+export interface MigrationSource {
+  /** Lightweight detector: does this content look like the expected source? */
+  detect(content: string): boolean;
+  /** Run the translation. */
+  transform(content: string, opts: MigrateOptions): Promise<MigrationResult>;
+}
+
 /**
  * Structured init template output from a lexicon plugin.
  */
@@ -194,6 +235,16 @@ export interface LexiconPlugin {
   /** Return MCP resource contributions */
   mcpResources?(): McpResourceContribution[];
 
+  // Migration
+  /**
+   * Return a migration source for translating from another lexicon's
+   * format into this lexicon. Returns undefined if `from` is not supported.
+   *
+   * Example: the gitlab lexicon implements `migrationSource("github")` to
+   * translate `.github/workflows/*.yml` into `.gitlab-ci.yml`.
+   */
+  migrationSource?(from: string): MigrationSource | undefined;
+
   // State
   /**
    * Query deployed resources and return API metadata. Opt-in.

package/src/lint/rule-registry.ts

@@ -83,7 +83,7 @@ export function buildRuleRegistry(
           source: plugin.name,
           phase: "post-synth",
           hasAutoFix: false,
-          helpUri: `https://chant.dev/lint-rules/${check.id.toLowerCase()}`,
+          helpUri: `https://intentius.io/chant/lint-rules/${check.id.toLowerCase()}`,
         });
       }
     }