@openparachute/hub 0.5.13-rc.13 → 0.5.13-rc.21

package/src/commands/upgrade.ts

@@ -7,7 +7,6 @@
  *
  *   bun-linked:   git -C <checkout> pull --ff-only;
  *                 bun install --frozen-lockfile (if package.json/bun.lock changed);
- *                 bun run build (frontend kind, if `build` script exists);
  *                 parachute restart <svc>.
  *
  *   npm-installed: bun add -g <pkg>@<tag>; parachute restart <svc>.
@@ -32,6 +31,19 @@
  * `bun add -g` to detect "already at latest" (the dist-tag didn't move).
  * Doing this avoids an unnecessary restart on a stable channel — a lot
  * cheaper than re-spawning a daemon that's already running the right code.
+ *
+ * Channel preservation (hub#332). The npm branch infers which dist-tag to
+ * use from the currently-installed version string: a `-rc(\.\d+)?$` suffix
+ * means the operator is on the rc chain → upgrade via `@rc`; otherwise
+ * `@latest`. This is load-bearing under pre-1.0 RC governance (parachute-
+ * patterns/patterns/governance.md rule 2): rc operators must stay on rc
+ * unless they explicitly promote. Before #332 the upgrade unconditionally
+ * pulled `@latest`, which silently downgraded an rc operator the moment
+ * `@latest` pointed at a prior stable. Operators can override the
+ * detection with `--channel rc|latest`. We also gate against silent
+ * downgrades: if `npm view <pkg>@<channel> version` resolves to something
+ * lower than what's installed, we abort with an actionable message
+ * (override with `--allow-downgrade`).
  */
 
 import { existsSync, readFileSync, realpathSync } from "node:fs";
@@ -101,8 +113,45 @@ export interface UpgradeOpts {
    * upgrade flow can be exercised without spawning real children.
    */
   restartFn?: (svc: string, opts: LifecycleOpts) => Promise<number>;
-  /** npm dist-tag for the npm-installed branch. Defaults to `latest`. Ignored when bun-linked. */
+  /**
+   * Explicit npm dist-tag for the npm-installed branch. When set, this
+   * overrides channel auto-detection AND the operator's `--channel` flag
+   * (it's a programmatic pin used by callers that already know what they
+   * want — e.g. tests). Operators don't pass `tag` directly; they pass
+   * `--channel rc|latest` which flows into `channel` below.
+   *
+   * Ignored when bun-linked.
+   */
   tag?: string;
+  /**
+   * Operator-facing channel override (`--channel rc|latest`). Bypasses the
+   * auto-detection that infers the channel from the currently-installed
+   * version string. When unset, `parachute upgrade` reads the installed
+   * package.json `version` and picks `@rc` if it matches `/-rc(\.\d+)?$/`,
+   * `@latest` otherwise.
+   *
+   * Per governance rule 2 (pre-1.0 RC versioning,
+   * `parachute-patterns/patterns/governance.md`), operators on the dev
+   * chain run `@rc`; `@latest` is the explicit-stable channel. The default
+   * `parachute upgrade` (pre hub#332) hard-coded `@latest`, which silently
+   * downgraded rc operators when `@latest` pointed at a prior stable.
+   */
+  channel?: "rc" | "latest";
+  /**
+   * Bypass the "refuses-to-downgrade" guard. The npm-install branch
+   * compares the target version (what `npm view <pkg>@<channel> version`
+   * resolves to) against the installed version and aborts if it would go
+   * backward. Set true to opt in to a real downgrade.
+   */
+  allowDowngrade?: boolean;
+  /**
+   * Test seam for resolving a dist-tag to a concrete version. Defaults to
+   * `npm view <pkg>@<channel> version` via the injected runner. Returning
+   * null is treated as "unknown — skip the downgrade guard" (network down,
+   * registry unreachable, package not yet published on that channel) so a
+   * flaky probe never blocks a legitimate upgrade.
+   */
+  resolveChannelVersion?: (pkg: string, channel: string) => Promise<string | null>;
 }
 
 interface ResolvedTarget {
@@ -119,7 +168,15 @@ interface Resolved {
   log: (line: string) => void;
   findGlobalInstall: (pkg: string) => string | null;
   restartFn: (svc: string, opts: LifecycleOpts) => Promise<number>;
-  tag: string;
+  /**
+   * Explicit pin (programmatic). When set, overrides both auto-detection
+   * and `channelOverride`. Undefined in the operator-facing default path.
+   */
+  tag: string | undefined;
+  /** Operator override (`--channel rc|latest`). Undefined → auto-detect. */
+  channelOverride: "rc" | "latest" | undefined;
+  allowDowngrade: boolean;
+  resolveChannelVersion: (pkg: string, channel: string) => Promise<string | null>;
 }
 
 function bunGlobalPrefixes(): string[] {
@@ -139,17 +196,119 @@ function defaultFindGlobalInstall(pkg: string): string | null {
 }
 
 function resolve(opts: UpgradeOpts): Resolved {
+  const runner = opts.runner ?? defaultRunner;
   return {
-    runner: opts.runner ?? defaultRunner,
+    runner,
     manifestPath: opts.manifestPath ?? SERVICES_MANIFEST_PATH,
     configDir: opts.configDir ?? CONFIG_DIR,
     log: opts.log ?? ((line) => console.log(line)),
     findGlobalInstall: opts.findGlobalInstall ?? defaultFindGlobalInstall,
     restartFn: opts.restartFn ?? ((svc, lifecycleOpts) => lifecycleRestart(svc, lifecycleOpts)),
-    tag: opts.tag ?? "latest",
+    tag: opts.tag,
+    channelOverride: opts.channel,
+    allowDowngrade: opts.allowDowngrade ?? false,
+    resolveChannelVersion:
+      opts.resolveChannelVersion ?? ((pkg, channel) => npmViewVersion(pkg, channel, runner)),
   };
 }
 
+/**
+ * Channel detection from a semver-ish version string. Pre-1.0 governance
+ * (parachute-patterns/patterns/governance.md rule 2) ships rc chains as
+ * `<x>.<y>.<z>-rc.<N>` (or sometimes `-rc` with no N). Anything matching that
+ * trailing suffix is the rc channel; everything else is the stable channel.
+ */
+export function detectChannel(installedVersion: string): "rc" | "latest" {
+  return /-rc(\.\d+)?$/.test(installedVersion) ? "rc" : "latest";
+}
+
+/**
+ * Inline semver-ish comparator. Returns < 0 / 0 / > 0 like `Array.prototype.sort`.
+ *
+ * Hub doesn't depend on `semver` and adding it for one call is overkill —
+ * npm dist-tags resolve to fully-qualified versions like `0.5.13-rc.13` or
+ * `0.5.10`, and we only need an ordering predicate ("would this be a
+ * downgrade?"). Spec compliance: split into [major, minor, patch] + an
+ * optional prerelease tail; numeric-compare the triple, then break ties by
+ * "no prerelease > has prerelease" (semver §11.4.3) and lex/numeric compare
+ * the prerelease dot-segments (§11.4.1–11.4.2). Returns null on malformed
+ * inputs so the caller can fail-open (skip the downgrade guard rather than
+ * block on a parser disagreement).
+ */
+export function compareVersions(a: string, b: string): number | null {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  if (!pa || !pb) return null;
+  for (let i = 0; i < 3; i++) {
+    const av = pa.parts[i] ?? 0;
+    const bv = pb.parts[i] ?? 0;
+    if (av !== bv) return av - bv;
+  }
+  // Equal triple: pre-release loses to no-pre-release.
+  if (pa.pre.length === 0 && pb.pre.length === 0) return 0;
+  if (pa.pre.length === 0) return 1;
+  if (pb.pre.length === 0) return -1;
+  // Both have pre-releases: dot-segment compare.
+  const len = Math.max(pa.pre.length, pb.pre.length);
+  for (let i = 0; i < len; i++) {
+    const av = pa.pre[i];
+    const bv = pb.pre[i];
+    if (av === undefined) return -1;
+    if (bv === undefined) return 1;
+    const an = /^\d+$/.test(av) ? Number(av) : null;
+    const bn = /^\d+$/.test(bv) ? Number(bv) : null;
+    if (an !== null && bn !== null) {
+      if (an !== bn) return an - bn;
+      continue;
+    }
+    if (an !== null) return -1; // numeric < non-numeric
+    if (bn !== null) return 1;
+    if (av < bv) return -1;
+    if (av > bv) return 1;
+  }
+  return 0;
+}
+
+function parseSemver(v: string): { parts: number[]; pre: string[] } | null {
+  // Tolerate a leading `v` and ignore build metadata after `+`.
+  const stripped = v.replace(/^v/, "").split("+")[0];
+  if (!stripped) return null;
+  const [core, ...preTail] = stripped.split("-");
+  if (!core) return null;
+  const partStrs = core.split(".");
+  if (partStrs.length < 1 || partStrs.length > 3) return null;
+  const parts: number[] = [];
+  for (const p of partStrs) {
+    if (!/^\d+$/.test(p)) return null;
+    parts.push(Number(p));
+  }
+  const pre = preTail.length === 0 ? [] : preTail.join("-").split(".").filter(Boolean);
+  return { parts, pre };
+}
+
+/**
+ * Resolve `<pkg>@<channel>` to a concrete version via `npm view`. Returns
+ * null when the probe fails (network down, registry unreachable, package
+ * not yet published on that channel) so callers can fail-open on the
+ * downgrade guard rather than block on a parser disagreement.
+ */
+async function npmViewVersion(
+  pkg: string,
+  channel: string,
+  runner: UpgradeRunner,
+): Promise<string | null> {
+  const { code, stdout } = await runner.capture(["npm", "view", `${pkg}@${channel}`, "version"]);
+  if (code !== 0) return null;
+  const trimmed = stdout.trim();
+  if (!trimmed) return null;
+  // `npm view <pkg>@<tag> version` prints a single line ("0.5.10\n").
+  // Tag points to no version → empty stdout → return null above.
+  // Belt-and-braces: take the last non-empty line in case npm decided to be
+  // chatty.
+  const lines = trimmed.split("\n").filter(Boolean);
+  return lines[lines.length - 1] ?? null;
+}
+
 /**
  * Synthetic services.json row for the hub. The hub isn't in services.json
  * (it's an implementation detail of `parachute expose`, not a user-facing
@@ -298,15 +457,6 @@ async function listChangedFiles(
   return stdout.trim().split("\n").filter(Boolean);
 }
 
-function packageHasScript(pkgJsonPath: string, name: string): boolean {
-  try {
-    const json = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
-    return Boolean(json?.scripts && typeof json.scripts[name] === "string");
-  } catch {
-    return false;
-  }
-}
-
 function readPackageVersion(pkgJsonPath: string): string | null {
   try {
     const json = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
@@ -373,26 +523,62 @@ async function upgradeLinked(
     }
   }
 
-  if (target.spec?.kind === "frontend") {
-    const pkgJsonPath = join(sourceDir, "package.json");
-    if (packageHasScript(pkgJsonPath, "build")) {
-      r.log(`${target.short}: bun run build`);
-      const build = await r.runner.run(["bun", "run", "build"], { cwd: sourceDir });
-      if (build !== 0) {
-        r.log(`✗ ${target.short}: bun run build failed (exit ${build})`);
-        return build;
-      }
-    }
-  }
-
   r.log(`${target.short}: ${before.sha.slice(0, 7)} → ${after.sha.slice(0, 7)}; restarting…`);
   return await r.restartFn(target.short, { manifestPath: r.manifestPath, configDir: r.configDir });
 }
 
+/**
+ * Pick which dist-tag we're going to ship at. Precedence:
+ *
+ *   1. explicit `tag` (programmatic — caller passed it directly)
+ *   2. operator `--channel rc|latest` flag
+ *   3. auto-detected from the installed version string (`-rc` suffix → rc)
+ *   4. `latest` fallback (no installed version to read — fresh-install case)
+ */
+function pickChannel(installedVersion: string | null, r: Resolved): string {
+  if (r.tag) return r.tag;
+  if (r.channelOverride) return r.channelOverride;
+  if (installedVersion) return detectChannel(installedVersion);
+  return "latest";
+}
+
 async function upgradeNpm(target: ResolvedTarget, sourceDir: string, r: Resolved): Promise<number> {
   r.log(`${target.short}: npm-installed (${sourceDir})`);
   const beforeVersion = readPackageVersion(join(sourceDir, "package.json"));
-  const spec = `${target.packageName}@${r.tag}`;
+  const channel = pickChannel(beforeVersion, r);
+
+  // Downgrade guard: refuse to silently move backward. Only applies when
+  // we can read both sides — beforeVersion from disk, targetVersion via
+  // `npm view`. A null on either side means we fail-open (legacy
+  // behavior: just run `bun add -g`). This is the load-bearing fix for
+  // hub#332 — Aaron got `0.5.13-rc.13` → `0.5.10` because the implicit
+  // `@latest` resolved to a prior stable while he was on the rc chain.
+  if (beforeVersion && !r.allowDowngrade) {
+    const targetVersion = await r.resolveChannelVersion(target.packageName, channel);
+    if (targetVersion) {
+      const cmp = compareVersions(targetVersion, beforeVersion);
+      if (cmp !== null && cmp < 0) {
+        const channelHint =
+          channel === "rc" ? "" : " or rerun with `--channel rc` to stay on the rc chain";
+        const rcNote =
+          channel === "rc"
+            ? "  (Unusual but possible: the @rc dist-tag may have been re-pointed at an older release.)"
+            : null;
+        r.log(
+          `✗ ${target.short}: refusing to downgrade — installed ${beforeVersion}, ` +
+            `target @${channel} resolves to ${targetVersion}.`,
+        );
+        if (rcNote) r.log(rcNote);
+        r.log(
+          `  To force this downgrade, run: bun add -g ${target.packageName}@${targetVersion}${channelHint}`,
+        );
+        r.log("  Or re-run with --allow-downgrade to bypass this check.");
+        return 1;
+      }
+    }
+  }
+
+  const spec = `${target.packageName}@${channel}`;
   r.log(`${target.short}: bun add -g ${spec}`);
   const code = await r.runner.run(["bun", "add", "-g", spec]);
   if (code !== 0) {

package/src/help.ts

@@ -34,8 +34,8 @@ export function installHelp(): string {
   return `parachute install — install and register a Parachute service
 
 Usage:
-  parachute install <service> [--tag <name>] [--no-start]
-  parachute install all       [--tag <name>] [--no-start]
+  parachute install <service> [--channel rc|latest] [--tag <name>] [--no-start]
+  parachute install all       [--channel rc|latest] [--tag <name>] [--no-start]
   parachute install scribe    [--scribe-provider <name>] [--scribe-key <key>]
 
 Services:
@@ -54,8 +54,14 @@ What it does:
   6. start the service in the background (idempotent — no-op if already up)
 
 Flags:
+  --channel rc|latest       npm dist-tag channel for the install. Defaults to
+                            \`latest\` unless \`PARACHUTE_INSTALL_CHANNEL\` is set
+                            (see Environment below). Loses to \`--tag\` (which
+                            pins an exact version / tag). Garbage env values
+                            fall back to \`latest\` with a warning.
   --tag <name>              npm dist-tag or exact version to install
-                            (e.g. \`--tag rc\` → \`bun add -g @openparachute/vault@rc\`)
+                            (e.g. \`--tag rc\` → \`bun add -g @openparachute/vault@rc\`).
+                            Wins over \`--channel\` and the env var.
                             Skipped if the package is already \`bun link\`-ed locally.
   --no-start                skip the post-install daemon start. For piped / CI
                             installs that own their own process model.
@@ -66,14 +72,25 @@ Flags:
                             Stored in ~/.parachute/scribe/.env. Only meaningful for
                             cloud providers (groq → GROQ_API_KEY, openai → OPENAI_API_KEY).
 
+Environment:
+  PARACHUTE_INSTALL_CHANNEL=rc|latest
+                            cluster-wide default channel. Lets a Render deploy
+                            running the hub at \`@rc\` cascade rc to vault / app /
+                            scribe / runner installed via the admin SPA — without
+                            an explicit \`--channel\` per call. Loses to \`--channel\`
+                            and \`--tag\`. Defaults to \`latest\` when unset.
+
 Examples:
   parachute install vault                                   # installs, runs init, starts vault
-  parachute install notes                                   # installs and starts notes
+  parachute install app                                     # installs app (auto-bootstraps Notes)
+  parachute install notes                                   # back-compat: legacy notes-daemon (Phase 2 deprecating)
   parachute install scribe                                  # installs, prompts for provider, starts scribe
   parachute install scribe --scribe-provider groq --scribe-key gsk_…
                                                             # non-interactive scribe setup
-  parachute install vault --tag rc                          # pin to rc dist-tag
-  parachute install all --tag rc                            # bootstrap whole ecosystem to rc
+  parachute install vault --channel rc                      # pin to rc dist-tag
+  PARACHUTE_INSTALL_CHANNEL=rc parachute install vault      # same, env-driven
+  parachute install vault --tag 0.3.0-rc.1                  # pin to an exact version (wins over --channel)
+  parachute install all --channel rc                        # bootstrap whole ecosystem to rc
   parachute install vault --no-start                        # install without auto-starting (CI)
 
 Aliases:
@@ -93,14 +110,14 @@ What it does:
   1. surveys ~/.parachute/services.json — already-installed services are
      reported, then skipped from the picker
   2. shows a numbered multi-select for the remaining first-party services
-     (vault, notes, scribe; channel is exploratory and only offered by name)
+     (vault, app, scribe; channel is exploratory and only offered by name)
   3. pre-collects all interactive answers up front so the installs can run
      without further prompting:
        - vault: vault name (default \`default\`)
        - scribe: transcription provider + API key for cloud providers
   4. iterates \`parachute install <svc>\` per pick, threading the collected
      answers and the shared --tag / --no-start flags
-  5. prints a summary banner with the running URLs (hub, vault, notes, scribe)
+  5. prints a summary banner with the running URLs (hub, vault, app, scribe)
      and a hint for connecting Claude Code
 
 Behavior:
@@ -109,7 +126,7 @@ Behavior:
     (root cause), so subsequent fallout doesn't mask the original problem.
   - Non-TTY / piped invocations should use \`parachute install <svc>\` per
     service instead — \`setup\` assumes a terminal for the prompts.
-  - Selection accepts numbers (\`1,3\`), names (\`vault, notes\`), or \`all\`.
+  - Selection accepts numbers (\`1,3\`), names (\`vault, app\`), or \`all\`.
 
 Flags:
   --tag <name>     npm dist-tag or exact version, applied to every install
@@ -155,8 +172,8 @@ Example:
   SERVICE          PORT  VERSION  PROCESS  PID    UPTIME  HEALTH  LATENCY  SOURCE
   parachute-vault  1940  0.2.4    running  12345  2h 13m  ok      2ms      bun-linked → parachute-vault @ 8aa167b
     → http://127.0.0.1:1940/vault/default/mcp
-  parachute-notes  1942  0.0.1    stopped  -      -       -       -        npm (0.3.15-rc.1)
-    → http://127.0.0.1:1942/notes
+  parachute-app    1946  0.2.0    running  12346  2h 12m  ok      3ms      npm (0.2.0-rc.4)
+    → http://127.0.0.1:1946/app/notes
 `;
 }
 
@@ -280,8 +297,9 @@ Start commands by service:
   hub       bun <cli>/hub-server.ts --port <picked> ...
   vault     parachute-vault serve
   scribe    parachute-scribe serve
+  app       parachute-app serve
   channel   parachute-channel daemon
-  notes     bun <cli>/notes-serve.ts --port <configured> --mount <paths[0]>
+  notes     bun <cli>/notes-serve.ts --port <configured> --mount <paths[0]>   # back-compat: legacy notes-daemon
 `;
 }
 
@@ -328,9 +346,17 @@ export function upgradeHelp(): string {
 Usage:
   parachute upgrade                 upgrade every installed service
   parachute upgrade <service>       upgrade just that one
+  parachute upgrade [svc] --channel rc|latest
+                                    pin the dist-tag channel explicitly. Default:
+                                    auto-detect from the installed version (a
+                                    \`-rc\` suffix → rc; otherwise latest).
+  parachute upgrade [svc] --allow-downgrade
+                                    bypass the "refuses to downgrade" guard.
   parachute upgrade [svc] --tag <name>
-                                    npm-installed services only — pin a dist-tag
-                                    (default: latest). Ignored when bun-linked.
+                                    npm-installed services only — pin to an
+                                    explicit dist-tag or exact version. Overrides
+                                    --channel auto-detection. Ignored when
+                                    bun-linked.
 
 What it does:
   Detects whether the target service is bun-linked from a local checkout
@@ -341,18 +367,29 @@ What it does:
                 modules with a build script, then \`parachute restart\`.
                 Refuses on a dirty working tree — commit or stash first.
 
-    npm         bun add -g <pkg>@<tag>, then \`parachute restart\` if the
-                installed version actually moved.
+    npm         bun add -g <pkg>@<channel>, then \`parachute restart\` if the
+                installed version actually moved. Refuses silent downgrades:
+                if the resolved channel version is lower than what's installed,
+                aborts with an actionable message.
 
   Idempotent: if the source didn't change (HEAD unchanged after pull, or
   package.json version unchanged after bun add -g), the restart is skipped.
   Re-running on an up-to-date install is a fast no-op.
 
+Channel detection (hub#332):
+  Pre-1.0 governance ships two channels — \`@rc\` (the development chain) and
+  \`@latest\` (explicitly-promoted stable). \`parachute upgrade\` reads the
+  installed package.json \`version\` and keeps you on the same channel: a
+  \`-rc\` suffix (e.g. \`0.5.13-rc.13\`) means you're on rc and the upgrade
+  pulls \`@rc\`; otherwise it pulls \`@latest\`. Override with \`--channel\`.
+
 Examples:
   parachute upgrade                 sweep hub + every installed service
   parachute upgrade vault           just vault
   parachute upgrade hub             upgrade the dispatcher itself (closes #251)
-  parachute upgrade vault --tag rc  pin the rc dist-tag (npm path only)
+  parachute upgrade hub --channel rc        pin the rc channel
+  parachute upgrade hub --channel latest    pin the stable channel
+  parachute upgrade vault --tag 0.4.1       pin to an exact version
 `;
 }
 

package/src/hub-server.ts

@@ -1534,6 +1534,11 @@ export function hubFetch(
         manifestPath: deps?.manifestPath ?? SERVICES_MANIFEST_PATH,
       };
       if (deps?.supervisor !== undefined) modulesDeps.supervisor = deps.supervisor;
+      // hub#342: thread the test-injectable module-manifest reader
+      // through so `management_url` resolution can be exercised in
+      // unit tests without writing real install dirs.
+      if (deps?.readModuleManifest !== undefined)
+        modulesDeps.readModuleManifest = deps.readModuleManifest;
       return handleApiModules(req, modulesDeps);
     }
 

package/src/hub.ts

@@ -357,6 +357,12 @@ const HTML_TEMPLATE = `<!doctype html>
     <p class="tagline">Your personal-computing modules.</p>
   </header>
 
+  <section class="section" id="get-started-section" hidden>
+    <h2>Get started</h2>
+    <p class="section-sub">Jump straight into what you came here for.</p>
+    <div class="grid" id="get-started-grid"></div>
+  </section>
+
   <section class="section" id="services-section">
     <h2>Services</h2>
     <p class="section-sub">Surfaces provided by services running on this hub.</p>
@@ -379,6 +385,8 @@ const HTML_TEMPLATE = `<!doctype html>
 (async () => {
   const servicesGrid = document.getElementById('services-grid');
   const adminGrid = document.getElementById('admin-grid');
+  const getStartedSection = document.getElementById('get-started-section');
+  const getStartedGrid = document.getElementById('get-started-grid');
 
   // Services entries are now data-driven from /.well-known/parachute.json.
   // Each services[] row carries (since hub#... — Phase D consumer side):
@@ -444,6 +452,68 @@ const HTML_TEMPLATE = `<!doctype html>
     }
   }
 
+  /**
+   * Render the "Get started" section (hub#342) above the Services grid.
+   *
+   * Two hardcoded targets, each conditional on its prerequisite being
+   * installed:
+   *   - "Open Notes" → /app/notes/  (requires parachute-app installed;
+   *     App auto-bootstraps Notes-as-UI per parachute-app §17, so the
+   *     mere presence of App means /app/notes/ is live)
+   *   - "Browse Vault" → /vault/<first-vault-name>/admin/  (requires
+   *     parachute-vault installed; uses the first vault's name from
+   *     its services.json mount path tail)
+   *
+   * If neither prerequisite is met (fresh install pre-wizard) the
+   * section stays hidden. The hardcoded shape mirrors the wizard's
+   * own done-screen "Start using your vault" tile — same architectural
+   * shape (single obvious entry point) at a different surface.
+   *
+   * Not driven by /api/modules because discovery is unauth — the
+   * services list from /.well-known/parachute.json is sufficient
+   * (it carries the same install-detection signal we need, no
+   * Bearer required).
+   */
+  function renderGetStarted(services) {
+    if (!getStartedGrid || !getStartedSection) return;
+    const tiles = [];
+    const hasApp = services.some((s) => s && s.name === 'parachute-app');
+    // services[] is fanned out per-vault for parachute-vault rows (see
+    // well-known.ts emitVaultRows) — "path" is the per-instance mount
+    // "/vault/<name>". Pick the first vault entry; the order matches
+    // services.json's paths[] order, so this is deterministic.
+    const vault = services.find((s) => s && s.name === 'parachute-vault');
+    if (hasApp) {
+      tiles.push({
+        title: 'Open Notes',
+        desc: 'Browse + capture in the Notes app — reads from your vault.',
+        href: '/app/notes/',
+      });
+    }
+    if (vault) {
+      // vault.path is the per-instance mount "/vault/<name>". Extract
+      // the tail as the display name; mirror the wizard's own
+      // firstVaultName() shape.
+      let vaultName = 'default';
+      if (typeof vault.path === 'string' && vault.path.startsWith('/vault/')) {
+        const tail = vault.path.slice('/vault/'.length).replace(/\/+$/, '');
+        if (tail.length > 0) vaultName = tail;
+      }
+      tiles.push({
+        title: 'Browse Vault',
+        desc: "Open your vault's admin UI — content, settings, MCP.",
+        href: '/vault/' + encodeURIComponent(vaultName) + '/admin/',
+      });
+    }
+    if (tiles.length === 0) {
+      getStartedSection.setAttribute('hidden', '');
+      return;
+    }
+    getStartedSection.removeAttribute('hidden');
+    getStartedGrid.innerHTML = '';
+    for (const tile of tiles) getStartedGrid.appendChild(renderTile(tile));
+  }
+
   function renderServices(services) {
     // Render one tile per service that declares a uiUrl. Entries without
     // uiUrl are intentionally omitted — vault is the canonical example
@@ -503,6 +573,7 @@ const HTML_TEMPLATE = `<!doctype html>
       if (!wk.ok) throw new Error('well-known fetch failed: ' + wk.status);
       const doc = await wk.json();
       const services = Array.isArray(doc.services) ? doc.services : [];
+      renderGetStarted(services);
       renderServices(services);
     } catch (err) {
       servicesGrid.innerHTML = '<div class="error">Could not load services: ' +

package/src/module-manifest.ts

@@ -24,8 +24,6 @@
 import { promises as fs } from "node:fs";
 import { join } from "node:path";
 
-export type ModuleKind = "api" | "frontend" | "tool";
-
 export interface ModuleScopeBlock {
   /** OAuth scopes this module owns. Namespaced by `name` per oauth-scopes.md. */
   readonly defines?: readonly string[];
@@ -76,8 +74,6 @@ export interface ModuleManifest {
   readonly displayName?: string;
   /** One-line subtitle rendered under displayName. */
   readonly tagline?: string;
-  /** Drives card vs. iframe vs. launcher in the hub. */
-  readonly kind: ModuleKind;
   /** Default loopback port. CLI warns on conflict, doesn't block. */
   readonly port: number;
   /** URL paths the module serves under the hub origin. */
@@ -167,13 +163,6 @@ function asOptionalString(v: unknown, where: string, field: string): string | un
   return v;
 }
 
-function asKind(v: unknown, where: string): ModuleKind {
-  if (v !== "api" && v !== "frontend" && v !== "tool") {
-    throw new ModuleManifestError(`${where}: "kind" must be "api" | "frontend" | "tool"`);
-  }
-  return v;
-}
-
 function asPort(v: unknown, where: string): number {
   if (typeof v !== "number" || !Number.isInteger(v) || v <= 0 || v > 65535) {
     throw new ModuleManifestError(`${where}: "port" must be an integer 1..65535`);
@@ -341,9 +330,20 @@ function asDependencies(v: unknown, where: string): Record<string, ModuleDepende
 /**
  * Strict validator. Throws `ModuleManifestError` with the source path so
  * malformed third-party modules get a clear-enough error to fix. Required
- * fields are name, manifestName, kind, port, paths, health.
+ * fields are name, manifestName, port, paths, health. The historical `kind`
+ * field is fully retired as of hub#301 Phase C/D (#330) — any value (or none)
+ * is silently ignored; modules and third parties may continue to ship it in
+ * `module.json` without error but hub no longer reads it.
+ *
+ * The optional `logger` parameter is retained for forward-compatibility
+ * with future validator soft-warnings, even though the kind soft-warning
+ * it was originally added for has been removed.
  */
-export function validateModuleManifest(raw: unknown, where: string): ModuleManifest {
+export function validateModuleManifest(
+  raw: unknown,
+  where: string,
+  _logger: Pick<Console, "warn"> = console,
+): ModuleManifest {
   if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
     throw new ModuleManifestError(`${where}: root must be an object`);
   }
@@ -356,7 +356,6 @@ export function validateModuleManifest(raw: unknown, where: string): ModuleManif
     );
   }
   const manifestName = asString(m.manifestName, where, "manifestName");
-  const kind = asKind(m.kind, where);
   const port = asPort(m.port, where);
   const paths = asStringArray(m.paths, where, "paths");
   const health = asHealthPath(m.health, where);
@@ -404,7 +403,7 @@ export function validateModuleManifest(raw: unknown, where: string): ModuleManif
     stripPrefix = m.stripPrefix;
   }
 
-  const out: ModuleManifest = { name, manifestName, kind, port, paths, health };
+  const out: ModuleManifest = { name, manifestName, port, paths, health };
   if (displayName !== undefined) (out as { displayName?: string }).displayName = displayName;
   if (tagline !== undefined) (out as { tagline?: string }).tagline = tagline;
   if (startCmd !== undefined) (out as { startCmd?: readonly string[] }).startCmd = startCmd;
@@ -470,8 +469,14 @@ function asPathOrUrl(v: unknown, where: string, field: string): string | undefin
  * absent (caller decides whether that's an error — first-party modules fall
  * back to the vendored manifest; third-party hard-errors). Throws
  * `ModuleManifestError` on parse / validation failure.
+ *
+ * The optional `logger` parameter is retained for forward-compatibility
+ * with future validator soft-warnings. Defaults to `console`.
  */
-export async function readModuleManifest(packageDir: string): Promise<ModuleManifest | null> {
+export async function readModuleManifest(
+  packageDir: string,
+  logger: Pick<Console, "warn"> = console,
+): Promise<ModuleManifest | null> {
   const path = join(packageDir, ".parachute", "module.json");
   let buf: string;
   try {
@@ -488,5 +493,5 @@ export async function readModuleManifest(packageDir: string): Promise<ModuleMani
       `${path}: failed to parse JSON: ${err instanceof Error ? err.message : String(err)}`,
     );
   }
-  return validateModuleManifest(parsed, path);
+  return validateModuleManifest(parsed, path, logger);
 }