create-pracht 0.6.1 → 0.6.2

package/src/index.js

@@ -1436,6 +1436,12 @@ function createAgentInstructions({ adapter, agentTools, packageManager, router,
   // needs the explicit `run` form the same way npm does.
   const runCmd =
     packageManager === "npm" || packageManager === "bun" ? `${packageManager} run` : packageManager;
+  // The pages router derives route ids from filenames, so the home page of a
+  // pages app is `index` (`src/pages/index.tsx`); the manifest scaffold names
+  // it `home` explicitly. Every id in the instructions below has to be one the
+  // scaffold actually generated, or the first link an agent writes is the very
+  // compile error these conventions exist to prevent.
+  const homeRouteId = router === "pages" ? "index" : "home";
 
   const lines = [
     "# Pracht App",
@@ -1540,6 +1546,21 @@ function createAgentInstructions({ adapter, agentTools, packageManager, router,
     lines.push("- `netlify.toml` — Netlify build, publish, and functions configuration");
   }
 
+  lines.push("");
+  lines.push("## Conventions");
+  lines.push("");
+  lines.push(
+    `- Navigate by route id, not by path: \`<Link route="${homeRouteId}">\`, ` +
+      `\`href("${homeRouteId}")\`, \`navigate({ route: "${homeRouteId}" })\`. Dynamic routes take ` +
+      "their segments through `params`. `<Link href>` is a type error — the id survives a path " +
+      "change and `pracht typegen` types both the id and its params. Use a plain `<a href>` for " +
+      "external and user-provided URLs.",
+  );
+  lines.push(
+    "- Run `pracht typegen` once to type route ids, params, and `apiFetch()`; `pracht dev` keeps " +
+      "them in sync.",
+  );
+
   if (agentTools) {
     lines.push("");
     lines.push("## Agent tooling");
@@ -1580,6 +1601,9 @@ function createReadme({
   const deployCommand = packageManager === "npm" ? "npm run deploy" : `${packageManager} deploy`;
   const typecheckCommand =
     packageManager === "npm" ? "npm run typecheck" : `${packageManager} typecheck`;
+  // The pages router derives route ids from filenames, so its home page is
+  // "index" where the manifest starter names it "home".
+  const homeRouteId = router === "pages" ? "index" : "home";
 
   const lines = [
     `# ${projectName}`,
@@ -1663,6 +1687,20 @@ function createReadme({
     lines.push("- `src/api/health.ts` is a sample API route.");
   }
 
+  // The one convention a new app trips over before it writes anything else,
+  // and AGENTS.md — where the same note lives for coding agents — is only
+  // seeded when agent tooling is enabled.
+  lines.push("");
+  lines.push("## Navigating");
+  lines.push("");
+  lines.push(
+    `Pracht navigates by route id, not by path: \`<Link route="${homeRouteId}">\`, ` +
+      `\`href("${homeRouteId}")\`, \`navigate({ route: "${homeRouteId}" })\`. Dynamic routes ` +
+      "take their segments through `params`. The id survives a path change, and `pracht " +
+      "typegen` types both the id and its params — so `<Link href>` is a compile error. Use a " +
+      "plain `<a href>` for external and user-provided URLs.",
+  );
+
   if (packageManager === "pnpm") {
     lines.push(
       pnpmWorkspaceNotice