feat: update CLI to use terminal-link for clickable URLs and enhance dependency documentation

Author: tinywaves

AGENTS.md

@@ -17,10 +17,38 @@
 
 ## Documentation
 
-- `docs/plans/` stores numbered implementation plans for features and milestones.
+- `docs/plans/` stores numbered implementation plans for features and milestones. Name files `NNN-short-slug.md` (hyphen-separated).
 - Before starting a new feature or refactor, read the relevant plan in `docs/plans/`.
 - Keep plans aligned with staged or merged implementation changes.
 
+### Plans
+
+Every plan in `docs/plans/` that touches package dependencies must include a **Dependency Changes** section with:
+
+- **Add**: package name(s) to install, with a one-line reason for each.
+- **Remove**: package name(s) to uninstall, with a one-line reason for each.
+- **Commands**: the exact `pnpm add` / `pnpm remove` commands for reference.
+
+Example:
+
+```markdown
+## Dependency Changes
+
+### Add
+- `terminal-link` — OSC 8 hyperlinks for clickable CLI URLs.
+
+### Remove
+- `consola` — only used for startup box; replaced by `terminal-link` + `console.info`.
+
+### Commands (manual only)
+pnpm remove consola
+pnpm add terminal-link
+```
+
+**Dependency commands are manual-only.** Do not run `pnpm add`, `pnpm remove`, or similar install/uninstall commands unless the user explicitly asks. List the commands in the plan; the user runs them by hand before or during implementation.
+
+**Persist plans after execution.** Once implementation is done, write the finalized plan into `docs/plans/` so it is versioned in the repo. Use the next sequential number and a short slug joined by hyphens, for example `002-clickable-cli-url.md`. The committed plan should match what was actually shipped—update goals, dependency changes, and verification steps if they diverged during implementation. Do not leave execution-only plans in ephemeral locations when the work is complete.
+
 ## Tooling
 
 - Use `pnpm` for all package operations.
@@ -46,7 +74,7 @@
 - Keep strict TypeScript settings satisfied; avoid weakening types to silence errors.
 - Prefer small, explicit exported APIs from `src/index.ts`.
 - Use `cac` for CLI startup and command parsing.
-- Use `consola` for CLI logging instead of direct `console.*` calls; prefer `consola.box` for CLI startup messages.
+- Use `terminal-link` for clickable CLI URLs; print startup messages with `console.info`.
 - Use `hono` with `@hono/node-server` for the local Web UI service; prefer simple Hono JSX views for the initial UI.
 - Preserve the package's side-effect-free behavior unless a feature explicitly requires otherwise.
 - Keep generated artifacts out of manual edits.

docs/plans/001_minimal-cli-webui.md docs/plans/001-minimal-cli-webui.mddocs/plans/001_minimal-cli-webui.md renamed to docs/plans/001-minimal-cli-webui.md

@@ -0,0 +1,56 @@
+# Clickable CLI Startup URL Plan
+
+## Goal
+
+Make the workspace URL printed at CLI startup clickable in modern terminals (Cursor/VS Code, iTerm2, WezTerm, etc.). Replace `consola.box` with a simple one-line startup message.
+
+The public package entrypoint in `src/index.ts` stays unchanged.
+
+## Architecture
+
+```mermaid
+flowchart TD
+  userShell["User Shell"] --> packageBin["bin/index.js"]
+  packageBin --> bundledBin["dist/bin/index.mjs"]
+  bundledBin --> cacDefault["cac Default Command"]
+  cacDefault --> startWebUi["startWebUiServer()"]
+  cacDefault --> terminalLink["terminal-link OSC 8"]
+  terminalLink --> consoleInfo["console.info"]
+  startWebUi --> honoApp["Hono App"]
+```
+
+## Dependency Changes
+
+### Add
+
+- `terminal-link` — wraps the URL in OSC 8 hyperlinks so supported terminals can open it with Cmd+click; uses `supports-hyperlinks` for capability detection.
+
+### Remove
+
+- `consola` — only used for `consola.box` on startup; replaced by `terminal-link` plus `console.info`.
+
+### Commands (manual only)
+
+```bash
+pnpm remove consola
+pnpm add terminal-link
+```
+
+## Implementation
+
+- `src/bin/index.ts` calls `terminalLink(webUi.url, webUi.url, { fallback: false })` and prints a one-line message via `console.info` after `startWebUiServer()`.
+- `AGENTS.md` updates CLI conventions: use `terminal-link` for clickable URLs; document plan dependency-change and post-execution persistence rules.
+
+## Behavior
+
+- Host remains hard-coded to `127.0.0.1`; port remains `7777`.
+- Startup output is a single line: `Foundry workspace is running at <url>`.
+- `fallback: false` keeps unsupported terminals from printing the URL twice.
+- Apple Terminal.app does not support OSC 8; the URL still displays as plain text.
+
+## Verification
+
+- `pnpm run lint`
+- `pnpm run test`
+- `pnpm run build`
+- Run `foundry` in Cursor terminal; Cmd+click the URL to open `http://127.0.0.1:7777`.

docs/plans/002-clickable-cli-url.md

@@ -84,7 +84,7 @@
   "dependencies": {
     "@hono/node-server": "^2.0.8",
     "cac": "^7.0.0",
-    "consola": "^3.4.2",
-    "hono": "^4.12.27"
+    "hono": "^4.12.27",
+    "terminal-link": "^5.0.0"
   }
 }

package.json

@@ -1,5 +1,5 @@
 import cac from 'cac';
-import { consola } from 'consola';
+import terminalLink from 'terminal-link';
 import { startWebUiServer } from './server';
 
 const cli = cac('foundry');
@@ -8,7 +8,12 @@ cli
   .command('[...args]', 'Open a local Foundry workspace')
   .action(() => {
     const webUi = startWebUiServer();
-    consola.box(`Foundry workspace is running at ${webUi.url}`);
+    const linkedUrl = terminalLink(
+      webUi.url,
+      webUi.url,
+      { fallback: false },
+    );
+    console.info(`Foundry workspace is running at ${linkedUrl}`);
   });
 
 cli.help();