showpane 0.4.13 → 0.4.15

package/README.md

@@ -22,7 +22,8 @@ Flags:
 
 ### `showpane login`
 Authenticate with Showpane Cloud for hosted portal deployment.
-This is auth only — org creation and billing happen in the Showpane Cloud web app.
+This is auth only. If the workspace is not billing/provisioning-ready yet, the
+cloud flow will send you to the relevant Showpane Cloud checkout or settings step.
 
 ### `showpane claude`
 Resume your Showpane workspace by launching Claude Code in the right project directory.

package/bundle/meta/scaffold-manifest.json

@@ -1,18 +1,18 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-04-09T23:30:19.010Z",
-  "scaffoldVersion": "0.2.4",
+  "generatedAt": "2026-04-11T21:50:01.081Z",
+  "scaffoldVersion": "0.2.6",
   "files": {
     ".env.example": "ed105f2bdcd1888a98181d55e3c9f7d6eff3ae9c3e2366c2e777a12e3caddfa7",
     ".gitignore": "998e5f43865ea56ac79a05acfd5d4b0d696f310bd5325a1ed458c3d40154d437",
-    "VERSION": "1725bfa6524c5265e7c171cf06568417d39b947fff49c242f03859479c82334b",
+    "VERSION": "be3c6d2c6c406a64d44f0b6464a887e290416dd90c524094485b1be00936d6d7",
     "next.config.ts": "cf27999cc274cce79bc4c8df11789807719abf40752b60e4b4967a3d2f0ed013",
     "package-lock.json": "d8e30eb86f08e70787d4459a084b4ab2a9f119696bbd3146ec4ba5675fffd3c2",
     "package.json": "b095e17e7fc181c630e87fe9f473c5a4ef969afcd4b110f9f9c6d6a6d93f1c0b",
     "postcss.config.js": "fa650b380adfabb151a0b352f7135e107e6352345f899060f1c5c231228f94bf",
     "prisma.config.ts": "36f56fd74eae70632e484443e38d08665158d72d5c978dc456651d8d5e1a636e",
     "prisma/schema.local.prisma": "f5d6f3cb17d6d229f46ef82eef7c0ff4261596924f0173fef075ac394f423073",
-    "prisma/seed.ts": "398b645c31ea0d5b0291f27c32aded22bdb64021e581a547e85b3cccca65c551",
+    "prisma/seed.ts": "bb8eb3bc189fabbab3be83d3909afee583a5b724d258139feda22af504bed134",
     "public/example-avatar.svg": "0edeb0d3fbefa89cc27ffe6564d20e3ee0fd073cb6d9f2a025248ef3b3f277fd",
     "public/example-logo.svg": "bc5cd933aff2a17698dee66a7b4ea940ad12238e9d813474d643b459b1e8d6da",
     "public/robots.txt": "331ea9090db0c9f6f597bd9840fd5b171830f6e0b3ba1cb24dfa91f0c95aedc1",
@@ -21,13 +21,13 @@
     "scripts/prisma-schema.mjs": "0a86cc1b5f84120948aed8f97a84f2d5b173f91a43ea34ad6767441894121d83",
     "src/__tests__/client-portals.test.ts": "9c3236bf0f7190b7d5ba9082287dcb29bc00d28dd63782a89505125ead06c624",
     "src/__tests__/deploy-bundle.test.ts": "abd3216170f306c09df6abb0d2afad966a5741e8859f25a310a0a09693d37609",
-    "src/__tests__/portal-contracts.test.ts": "80066377d3281786c2bb9ecc857514124e094a2e66dca2fb08ded994c25fa2bc",
+    "src/__tests__/portal-contracts.test.ts": "9562b67f84f528ee0bb0bc4c0225adaf1dcc38c59b7629bda7c44e374a020eac",
     "src/app/(portal)/client/[slug]/page.tsx": "4f2f9253b2ad5d37a0f13759db52c786ae9c401f50fae9431da1417e9736e000",
     "src/app/(portal)/client/[slug]/s/[token]/route.ts": "a445e54b9139e40dfe0bc039e34e6af224a27f75a614741ab224d317ad4d3ec9",
-    "src/app/(portal)/client/example/example-client.tsx": "b9b744f0358b7773f319757157598fc69059eb38e0eaa1c09cb5fc10cfc3894b",
+    "src/app/(portal)/client/example/example-client.tsx": "ed32b111acea861f448d865338f8841d47c6ca7c2f87ed30d85bb0804940d4ec",
     "src/app/(portal)/client/example/page.tsx": "f330864f63c9feea76c8a62c3eba3ce57578627e0d4abd929fd7fefdfc7af058",
     "src/app/(portal)/client/layout.tsx": "4f43871510408a81da229d48ae316ec1d1c1beda93121922246300a2c8fd0999",
-    "src/app/(portal)/client/page.tsx": "af36f1a6f359d6a7bd4a6ac550058c9d9c107e9885bb238b4c06ec26700e23e3",
+    "src/app/(portal)/client/page.tsx": "7b4e3e5b286672f83581e24349e98ac930d8bbf5dfed02793754be2ddadf430f",
     "src/app/api/client-auth/route.ts": "ce1858559b1e944d5b1dc719d1f03bebf66286671700b1b5397382109f0f1e0d",
     "src/app/api/client-auth/share/route.ts": "ed82414212dcd26af8c6c0f2bd44d9d79a727ed35cfedbac8c4077a6220aad14",
     "src/app/api/client-events/route.ts": "13d545537b7e8ce421e6169d25c105adf2a2de3d978ae0a2c6751ff5f7d2eb33",
@@ -38,10 +38,10 @@
     "src/app/api/health/route.ts": "78fff55707372ce0cd6e9e49ef4f049622bc43cc42916d3f83e0162409d678b1",
     "src/app/globals.css": "28dcda76006d0e6af01b6dcf1a315dc5b5b6931c880fc53fd6565ff09d5dd13a",
     "src/app/layout.tsx": "c17aabeb2b486f023e777230343ace6cc06840f641a10b9dd9f65e092018f82f",
-    "src/app/page.tsx": "732ea54f313386b65bce1170785379b27bb26b5da26b833b1e50c3713b87be1a",
+    "src/app/page.tsx": "1f71205c3ae30bf6929d37947b0c94ae53aed33b6689b7d6b13066ad51c1bc14",
     "src/components/copy-button.tsx": "2f3d1d8a6a0a570c8d78e19c3c15519c44af17b5d8893ae5a5f57db5ecce7077",
     "src/components/portal-login.tsx": "8b0d91bb28674e1102fd2e5b5ddcc3a93755dd806fbd3d1b2dbea2646cffca5e",
-    "src/components/portal-shell.tsx": "a4e16e118ef93f79e71fb69e80f1fac6e6fff90f0fbdacdf8deb821a57656877",
+    "src/components/portal-shell.tsx": "f46a0f753a4a0318f06c8b4e46295febb84b03ea082c95057a6da50c737b4e21",
     "src/lib/abuse-controls.ts": "d79d58d93267aca48ad0b7b9b91f753c9a3c27263e4e98daf768a950c44a6fc6",
     "src/lib/branding.ts": "cc55f40e02bc3e486b227988f95739ca1cda8012c97b591295995eb4465efd57",
     "src/lib/client-auth.ts": "b9bdfe77dbe5d6ec6c6a930627fc43d3253f0d76fd8fc4093af5a75742bebe42",
@@ -51,7 +51,7 @@
     "src/lib/deploy-bundle.ts": "e9675cccb2c802e408639481986c6b629737541853e1c93f322c08a5b9dfc5f9",
     "src/lib/files.ts": "24fd8d1d53c180d62441019395fb140ba3baa28311918ac488284adcdda8eb9a",
     "src/lib/load-app-env.ts": "78b80e17d896885f0d72315ee9a6cf7a0a8c6c08171f26e3d599bb9b2e8afeee",
-    "src/lib/portal-contracts.ts": "519a97afe3ae618077c95aba5a9764383e7edf6c9effd62a5638a50a0b2a676a",
+    "src/lib/portal-contracts.ts": "7954e5c66ebc2159d77d0b4c3a5f0d0a561ab020de8cefb0ddd52c7688039108",
     "src/lib/prisma-client.ts": "28cd100129a0178a6c8fdfe49e6997b19983fcc427b9fa7caee3ac26226e5eb3",
     "src/lib/runtime-state.ts": "3d30de7dfeaaa48d8b6fd5d29976ecd001408172100c95b063d5d804fdce0a2e",
     "src/lib/storage.ts": "ae3b85fc6cccd39d4174a391dcbe6e91fb9460eb407ec9dbfedd63594a441d08",

package/bundle/scaffold/VERSION

@@ -1 +1 @@
-0.2.4
+0.2.6

package/bundle/scaffold/prisma/seed.ts

@@ -1,49 +1,54 @@
 import { PrismaClient } from "@/lib/prisma-client";
-import bcrypt from "bcryptjs";
 
 const prisma = new PrismaClient();
 
+function normalizeSlug(value: string): string {
+  return value
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9\s-]/g, "")
+    .replace(/\s+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+function normalizeWebsiteUrl(value: string | undefined): string | null {
+  if (!value) return null;
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  return trimmed.startsWith("http://") || trimmed.startsWith("https://")
+    ? trimmed
+    : `https://${trimmed}`;
+}
+
 async function main() {
-  const org = await prisma.organization.upsert({
-    where: { slug: "demo" },
-    update: {},
-    create: {
-      name: "Demo Company",
-      slug: "demo",
-      contactName: "Jane Smith",
-      contactTitle: "Account Manager",
-      contactEmail: "jane@example.com",
-      supportEmail: "support@example.com",
-      websiteUrl: "https://example.com",
-    },
-  });
+  const organizationName = process.env.SHOWPANE_ORG_NAME?.trim();
+  if (!organizationName) {
+    console.log("Seed skipped: no organization details provided");
+    return;
+  }
 
-  const passwordHash = await bcrypt.hash("demo-only-password", 10);
+  const organizationSlug =
+    process.env.SHOWPANE_ORG_SLUG?.trim() || normalizeSlug(organizationName);
+  const contactName = process.env.SHOWPANE_CONTACT_NAME?.trim() || null;
+  const contactEmail = process.env.SHOWPANE_CONTACT_EMAIL?.trim() || null;
+  const websiteUrl = normalizeWebsiteUrl(process.env.SHOWPANE_WEBSITE_URL);
 
-  await prisma.clientPortal.upsert({
-    where: {
-      organizationId_slug: {
-        organizationId: org.id,
-        slug: "example",
-      },
-    },
-    update: {
-      companyName: "Acme Health",
-      username: "example",
-      passwordHash,
-      lastUpdated: "2 April 2026",
-    },
+  const org = await prisma.organization.upsert({
+    where: { slug: organizationSlug },
+    update: {},
     create: {
-      organizationId: org.id,
-      slug: "example",
-      companyName: "Acme Health",
-      username: "example",
-      passwordHash,
-      lastUpdated: "2 April 2026",
+      name: organizationName,
+      slug: organizationSlug,
+      contactName,
+      contactTitle: null,
+      contactEmail,
+      supportEmail: contactEmail,
+      websiteUrl,
     },
   });
 
-  console.log("Seed complete: org 'demo', portal 'example' (username: example, password: demo-only-password)");
+  console.log(`Seed complete: org '${org.slug}'`);
 }
 
 main()

package/bundle/scaffold/src/__tests__/portal-contracts.test.ts

@@ -2,6 +2,8 @@ import { describe, expect, it } from "vitest";
 
 import {
   ANALYTICS_METADATA_KEYS,
+  ORGANIZATION_NOT_READY_ERROR,
+  ORGANIZATION_REQUIRED_ERROR,
   isPortalEventType,
   toCloudPortalEventPayload,
 } from "@/lib/portal-contracts";
@@ -29,4 +31,9 @@ describe("portal contracts", () => {
       metadata: { durationSeconds: 12 },
     });
   });
+
+  it("exports the shared cloud auth error codes", () => {
+    expect(ORGANIZATION_REQUIRED_ERROR).toBe("organization_required");
+    expect(ORGANIZATION_NOT_READY_ERROR).toBe("organization_not_ready");
+  });
 });

package/bundle/scaffold/src/app/(portal)/client/example/example-client.tsx

@@ -1,9 +1,8 @@
 "use client";
 
 /**
- * Reference portal — the /portal create skill reads this file as the quality
+ * Reference portal — the /portal-create skill reads this file as the quality
  * and style guide when generating new portals. Keep it polished.
- * Login: username "example", password "demo-only-password" (seeded by prisma/seed.ts)
  */
 
 import { type ReactNode } from "react";

package/bundle/scaffold/src/app/(portal)/client/page.tsx

@@ -5,14 +5,15 @@ import { PortalLogin } from "@/components/portal-login";
 export default function ClientLogin() {
   return (
     <PortalLogin
-      companyName="Demo Company"
+      companyName="Your Portal"
       companyLogo={
         <div className="flex h-7 w-7 items-center justify-center rounded-lg bg-gray-900">
-          <span className="text-xs font-bold text-white">D</span>
+          <span className="text-xs font-bold text-white">P</span>
         </div>
       }
-      companyUrl="https://example.com"
-      supportEmail="support@example.com"
+      companyUrl="https://showpane.com"
+      supportEmail="support@showpane.com"
+      description="Private portal access. Sign in with the credentials you were sent."
     />
   );
 }

package/bundle/scaffold/src/app/page.tsx

@@ -2,7 +2,13 @@ import { CopyButton } from "@/components/copy-button";
 import { resolveDefaultOrganizationId } from "@/lib/client-portals";
 import { prisma } from "@/lib/db";
 import { getRuntimeState, isRuntimeSnapshotMode } from "@/lib/runtime-state";
-import { ArrowUpRight, BookOpen, Command, MessageSquareQuote } from "lucide-react";
+import {
+  ArrowUpRight,
+  BookOpen,
+  Command,
+  MessageSquareQuote,
+  Sparkles,
+} from "lucide-react";
 import Link from "next/link";
 import { existsSync, readFileSync } from "node:fs";
 import os from "node:os";
@@ -60,7 +66,8 @@ export default async function Home() {
             Your Showpane workspace is ready
           </h1>
           <p className="mt-4 max-w-2xl text-base leading-7 text-white/82 sm:text-lg">
-            Open a new terminal window, run Showpane with Claude, and create your first client portal.
+            Open a new terminal window, start Showpane with Claude, then run the
+            guided first-portal wizard.
           </p>
         </div>
       </div>
@@ -72,7 +79,7 @@ export default async function Home() {
               <div>
                 <div className="flex items-center gap-2 text-sm font-semibold text-white/80">
                   <Command className="h-4 w-4" />
-                  Start with Claude
+                  Step 1: Start with Claude
                 </div>
                 <p className="mt-3 text-sm leading-6 text-white/72">
                   Open a new terminal window and run this command there. Your current terminal is running the local app, so this command belongs in a fresh one.
@@ -94,12 +101,41 @@ export default async function Home() {
             </div>
           </section>
 
+          <section className="rounded-[28px] border border-slate-200 bg-white p-6 shadow-[0_20px_70px_rgba(15,23,42,0.07)] sm:p-7">
+            <div className="flex items-center gap-2 text-sm font-semibold text-slate-700">
+              <Sparkles className="h-4 w-4" />
+              Step 2: Run the first-portal wizard
+            </div>
+
+            <p className="mt-3 text-sm leading-6 text-slate-600">
+              If this is your first portal, use the guided path. It walks through
+              draft creation, preview, access setup, and the hosted publish handoff.
+            </p>
+
+            <div className="mt-5 flex items-start justify-between gap-4 rounded-2xl border border-slate-200 bg-slate-50 p-4">
+              <div>
+                <p className="text-[11px] font-semibold uppercase tracking-[0.18em] text-slate-400">
+                  Recommended
+                </p>
+                <p className="mt-3 font-mono text-sm leading-6 text-slate-700">
+                  /portal-onboard
+                </p>
+              </div>
+              <CopyButton text="/portal-onboard" />
+            </div>
+          </section>
+
           <section className="rounded-[28px] border border-slate-200 bg-white p-6 shadow-[0_20px_70px_rgba(15,23,42,0.07)] sm:p-7">
             <div className="flex items-center gap-2 text-sm font-semibold text-slate-700">
               <MessageSquareQuote className="h-4 w-4" />
-              What to say to Claude
+              Prefer the manual path?
             </div>
 
+            <p className="mt-3 text-sm leading-6 text-slate-600">
+              Freeform prompts still work well once you know the shape you want.
+              Use them when you want the fast repeat-user path instead of the wizard.
+            </p>
+
             <div className="mt-5 space-y-3">
               {PROMPT_EXAMPLES.map((example, index) => (
                 <div
@@ -125,10 +161,11 @@ export default async function Home() {
               <div className="max-w-xl">
                 <div className="flex items-center gap-2 text-sm font-semibold text-[#214668]">
                   <BookOpen className="h-4 w-4" />
-                  Need help creating your first portal?
+                  Need examples before you run the wizard?
                 </div>
                 <p className="mt-3 text-base leading-7 text-[#284f74]">
-                  Follow the step-by-step guide with examples, best practices, and a walkthrough video.
+                  The first-portal guide now focuses on the recommended wizard path,
+                  plus examples and manual prompting patterns.
                 </p>
               </div>
               <a

package/bundle/scaffold/src/components/portal-shell.tsx

@@ -180,6 +180,7 @@ export function PortalShell({
   const [copied, setCopied] = useState(false);
   const [copyError, setCopyError] = useState(false);
   const [visitorId] = useState(() => getOrCreateVisitorId());
+  const [showLocalBanner, setShowLocalBanner] = useState(false);
 
   useEffect(() => {
     const syncFromHash = () => setActiveTab(readHashTab(tabIds));
@@ -200,6 +201,12 @@ export function PortalShell({
     return () => window.clearTimeout(timeout);
   }, [copied, copyError]);
 
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    const host = window.location.hostname;
+    setShowLocalBanner(host === "localhost" || host === "127.0.0.1" || host === "0.0.0.0");
+  }, []);
+
   useSectionTimeTracking(activeTab, resolvedEventsEndpoint, visitorId);
 
   function switchTab(tab: string) {
@@ -232,6 +239,22 @@ export function PortalShell({
   return (
     <div className="flex min-h-screen flex-col bg-gray-50">
       <div className="sticky top-0 z-30 border-b border-gray-200 bg-white/95 backdrop-blur">
+        {showLocalBanner && (
+          <div className="border-b border-amber-200 bg-amber-50">
+            <div className="mx-auto flex max-w-4xl items-center gap-2 px-4 py-2 text-[11px] font-medium text-amber-900 sm:px-6 sm:text-xs">
+              <span className="inline-flex shrink-0 whitespace-nowrap rounded-full bg-amber-200 px-2 py-0.5 text-[10px] font-semibold uppercase tracking-[0.14em] text-amber-900 sm:text-[11px]">
+                Local preview
+              </span>
+              <span>
+                This portal is local only. Tell Claude{" "}
+                <code className="rounded bg-white px-1.5 py-0.5 font-mono text-[11px] text-amber-950 sm:text-xs">
+                  /portal-deploy
+                </code>{" "}
+                to publish it to Showpane Cloud.
+              </span>
+            </div>
+          </div>
+        )}
         <header className="border-b bg-white/90">
           <div className="mx-auto flex max-w-4xl items-center justify-between px-4 py-3 sm:px-6">
             <div className="flex items-center gap-3">

package/bundle/scaffold/src/lib/portal-contracts.ts

@@ -12,6 +12,39 @@ export const PORTAL_EVENT_TYPES = [
 
 export type PortalEventType = (typeof PORTAL_EVENT_TYPES)[number];
 export const ORGANIZATION_REQUIRED_ERROR = "organization_required" as const;
+export const ORGANIZATION_NOT_READY_ERROR = "organization_not_ready" as const;
+
+export const WORKSPACE_NEXT_ACTIONS = [
+  "open_checkout",
+  "wait_for_provisioning",
+  "open_settings",
+  "manage_billing",
+] as const;
+
+export type WorkspaceNextAction = (typeof WORKSPACE_NEXT_ACTIONS)[number];
+
+export const WORKSPACE_READINESS_REASONS = [
+  "billing_inactive",
+  "provisioning",
+  "provisioning_issue",
+  "workspace_incomplete",
+] as const;
+
+export type WorkspaceReadinessReason =
+  (typeof WORKSPACE_READINESS_REASONS)[number];
+
+export interface OrganizationNotReadyPayload {
+  code: typeof ORGANIZATION_NOT_READY_ERROR;
+  error: string;
+  orgSlug: string;
+  provisioningStatus: string | null;
+  subscriptionStatus: string | null;
+  isActive: boolean;
+  checkoutUrl?: string;
+  settingsUrl: string;
+  nextAction: WorkspaceNextAction;
+  reason: WorkspaceReadinessReason;
+}
 
 export const ANALYTICS_METADATA_KEYS = {
   durationSeconds: "durationSeconds",

package/bundle/toolchain/CLI_VERSION

@@ -0,0 +1 @@
+0.4.15

package/bundle/toolchain/TELEMETRY_CONFIG.json

@@ -0,0 +1,4 @@
+{
+  "baseUrl": "https://app.showpane.com",
+  "ingestPath": "/api/telemetry/ingest"
+}

package/bundle/toolchain/VERSION

@@ -1 +1 @@
-1.1.4 (requires app >= 0.2.4)
+1.1.6 (requires app >= 0.2.6)

package/bundle/toolchain/bin/ensure-cloud-project-link.ts

@@ -1,6 +1,17 @@
 import fs from "node:fs";
 import path from "node:path";
 
+const ORGANIZATION_REQUIRED_ERROR = "organization_required";
+const ORGANIZATION_NOT_READY_ERROR = "organization_not_ready";
+
+type OrganizationNotReadyPayload = {
+  code: typeof ORGANIZATION_NOT_READY_ERROR;
+  error: string;
+  orgSlug: string;
+  reason: string;
+  nextAction: string;
+};
+
 type ShowpaneConfig = {
   accessToken?: string;
 };
@@ -50,7 +61,29 @@ async function main() {
   });
 
   if (!res.ok) {
-    fail(`Could not fetch cloud project link (${res.status})`);
+    const rawBody = await res.text();
+    let body: { code?: string } | null = null;
+    if (rawBody) {
+      try {
+        body = JSON.parse(rawBody) as { code?: string };
+      } catch {
+        body = null;
+      }
+    }
+    if (body?.code === ORGANIZATION_REQUIRED_ERROR) {
+      fail("Showpane Cloud workspace required. Finish checkout, then retry.");
+    }
+    if (body?.code === ORGANIZATION_NOT_READY_ERROR) {
+      const details = body as OrganizationNotReadyPayload;
+      fail(
+        `Workspace ${details.orgSlug} is not ready: ${details.error} (${details.reason}, next: ${details.nextAction}).`,
+      );
+    }
+    fail(
+      rawBody
+        ? `Could not fetch cloud project link (${res.status}): ${rawBody}`
+        : `Could not fetch cloud project link (${res.status})`,
+    );
   }
 
   const projectLink = await res.json() as CloudProjectLink;

package/bundle/toolchain/bin/showpane-config

@@ -5,55 +5,134 @@ CONFIG_DIR="${HOME}/.showpane"
 CONFIG_FILE="${CONFIG_DIR}/config.json"
 
 usage() {
-  echo "Usage: showpane-config <get|set> <key> [value]"
-  echo ""
-  echo "Commands:"
-  echo "  get <key>          Read a value from config"
-  echo "  set <key> <value>  Write a value to config"
-  echo ""
-  echo "Config file: ${CONFIG_FILE}"
+  cat <<'EOF'
+Usage: showpane-config <get|set|unset|has|path> <key> [value]
+
+Commands:
+  get <key>           Read a value from config
+  set <key> <value>   Write a scalar value to config
+  unset <key>         Remove a key from config
+  has <key>           Exit 0 if key exists, 1 otherwise
+  path                Print the config file path
+
+Notes:
+  - Keys support dot notation, e.g. "cloud.portalUrl"
+  - Values "true", "false", "null", and numeric literals are parsed as JSON scalars
+  - Everything else is stored as a string
+EOF
   exit 1
 }
 
 ensure_config() {
-  if [ ! -d "$CONFIG_DIR" ]; then
-    mkdir -p "$CONFIG_DIR"
-  fi
+  mkdir -p "$CONFIG_DIR"
   if [ ! -f "$CONFIG_FILE" ]; then
     echo '{}' > "$CONFIG_FILE"
     chmod 600 "$CONFIG_FILE"
   fi
 }
 
+py_get='
+import json, sys
+path, key = sys.argv[1], sys.argv[2]
+with open(path) as fh:
+    data = json.load(fh)
+node = data
+for part in key.split("."):
+    if not isinstance(node, dict) or part not in node:
+        raise SystemExit(1)
+    node = node[part]
+if isinstance(node, bool):
+    print("true" if node else "false")
+elif node is None:
+    print("null")
+elif isinstance(node, (dict, list)):
+    print(json.dumps(node))
+else:
+    print(node)
+'
+
+py_has='
+import json, sys
+path, key = sys.argv[1], sys.argv[2]
+with open(path) as fh:
+    data = json.load(fh)
+node = data
+for part in key.split("."):
+    if not isinstance(node, dict) or part not in node:
+        raise SystemExit(1)
+    node = node[part]
+raise SystemExit(0)
+'
+
+py_set='
+import json, sys
+path, key, raw = sys.argv[1], sys.argv[2], sys.argv[3]
+with open(path) as fh:
+    data = json.load(fh)
+try:
+    value = json.loads(raw)
+except Exception:
+    value = raw
+node = data
+parts = key.split(".")
+for part in parts[:-1]:
+    current = node.get(part)
+    if not isinstance(current, dict):
+        current = {}
+        node[part] = current
+    node = current
+node[parts[-1]] = value
+with open(path, "w") as fh:
+    json.dump(data, fh, indent=2)
+    fh.write("\n")
+'
+
+py_unset='
+import json, sys
+path, key = sys.argv[1], sys.argv[2]
+with open(path) as fh:
+    data = json.load(fh)
+node = data
+parts = key.split(".")
+for part in parts[:-1]:
+    current = node.get(part)
+    if not isinstance(current, dict):
+        raise SystemExit(1)
+    node = current
+if parts[-1] not in node:
+    raise SystemExit(1)
+del node[parts[-1]]
+with open(path, "w") as fh:
+    json.dump(data, fh, indent=2)
+    fh.write("\n")
+'
+
 case "${1:-}" in
   get)
     [ -z "${2:-}" ] && usage
     ensure_config
-    # Use python3 for portable JSON parsing (available on macOS + Linux)
-    python3 -c "
-import json, sys
-with open('$CONFIG_FILE') as f:
-    data = json.load(f)
-key = '$2'
-if key in data:
-    print(data[key])
-else:
-    sys.exit(1)
-"
+    python3 -c "$py_get" "$CONFIG_FILE" "$2"
     ;;
   set)
     [ -z "${2:-}" ] || [ -z "${3:-}" ] && usage
     ensure_config
-    python3 -c "
-import json
-with open('$CONFIG_FILE') as f:
-    data = json.load(f)
-data['$2'] = '$3'
-with open('$CONFIG_FILE', 'w') as f:
-    json.dump(data, f, indent=2)
-"
+    python3 -c "$py_set" "$CONFIG_FILE" "$2" "$3"
     chmod 600 "$CONFIG_FILE"
     ;;
+  unset)
+    [ -z "${2:-}" ] && usage
+    ensure_config
+    python3 -c "$py_unset" "$CONFIG_FILE" "$2"
+    chmod 600 "$CONFIG_FILE"
+    ;;
+  has)
+    [ -z "${2:-}" ] && usage
+    ensure_config
+    python3 -c "$py_has" "$CONFIG_FILE" "$2"
+    ;;
+  path)
+    printf '%s\n' "$CONFIG_FILE"
+    ;;
   --help|-h)
     usage
     ;;