{
  "slug": "knot-setupcli",
  "name": "Knot",
  "displayName": "Knot Command Center",
  "tagline": "Trip command center — setup utility and mobile Server Mode guide",
  "summary": "Plain-language setup for organizers running the Knot setup utility on a Mac, Windows PC, or Linux machine, then connecting the iOS or Android app in Server Mode. No phone-home — this page is pull-only knowledge for humans and LLM helpers.",
  "twoFaces": "Human page at https://knot.llmtech.net/setupcli/ · machine dump at https://knot.llmtech.net/content/knot-setupcli.json",
  "version": "1.0.0",
  "released": "2026-06-30",
  "identity": {
    "bundleId": "net.llmtech.knot",
    "repo": "https://github.com/Everplay-Tech/knot"
  },
  "modes": {
    "server_mode": {
      "title": "Server Mode",
      "summary": "You run Knot on a computer you control (or a cloud host). The mobile app connects to that server URL for encrypted sync, voice, camera capture, and the full planner workflow.",
      "best_for": [
        "Organizers who want the full Knot experience on phones",
        "Trips that need voice queries and camera ticket capture",
        "Groups that want a URL everyone can bookmark or install as a home-screen app"
      ],
      "you_need": [
        "A host computer or cloud server",
        "The Knot setup utility finished once on that host",
        "A server URL that phones can reach (usually HTTPS, not localhost)"
      ]
    },
    "cloud_mode": {
      "title": "Cloud Mode",
      "summary": "You deploy Knot to a hosted platform (Railway is the built-in path in the setup utility). The mobile app still connects with a server URL — it is just served from the cloud instead of your home computer.",
      "best_for": [
        "Organizers who do not want to keep a home computer running",
        "Trips where a stable public HTTPS URL is easier than Tailscale",
        "Quick first trips when Docker on a VPS is more than you want today"
      ],
      "you_need": [
        "A Railway account (or another host you configure yourself)",
        "Option 2 in the setup utility, or the manual Railway steps in this guide",
        "The HTTPS URL Railway prints when deployment finishes"
      ]
    }
  },
  "setup_utility": {
    "title": "Knot setup utility",
    "description": "Interactive installer in the Knot repo. It checks dependencies, walks you through Docker Compose, Railway, or bare-metal paths, and prints the setup URL plus OWNER setup code.",
    "commands": {
      "mac_linux": "./scripts/knot-cli",
      "windows_powershell": ".\\scripts\\knot-cli.ps1"
    },
    "before_you_start": [
      "Clone or download the Knot repo to the host computer.",
      "Open Terminal (Mac/Linux) or PowerShell (Windows) in the KNOT folder — the folder that contains the scripts directory.",
      "Run the command for your operating system and follow the numbered menu."
    ],
    "menu_options": [
      {
        "id": "docker",
        "label": "1) Docker Compose (this machine)",
        "summary": "Recommended for a home server or VPS with Docker. Caddy can provide HTTPS when you use a real domain."
      },
      {
        "id": "railway",
        "label": "2) Railway (cloud)",
        "summary": "Deploy to Railway with a persistent volume. Matches Cloud Mode in the mobile app."
      },
      {
        "id": "bare_metal",
        "label": "3) Bare metal (no Docker)",
        "summary": "Build and run on the host with Rust and Node.js. Good for developers; local URL is usually http://localhost:8787 for setup only."
      }
    ],
    "after_utility_finishes": [
      "Open the Setup URL in a browser on the host computer (ends with /setup).",
      "Enter the Setup Code from the terminal logs (format OWNER-XXXXXXXX).",
      "Copy the final server URL (https://… or Tailscale https://….ts.net) for the mobile app."
    ]
  },
  "paths": {
    "mac_or_linux": {
      "title": "Mac or Linux",
      "steps": [
        "Open Terminal and cd into your KNOT folder.",
        "Make the script executable once: chmod +x scripts/knot-cli",
        "Run: ./scripts/knot-cli",
        "Pick Docker (1), Railway (2), or bare metal (3).",
        "When you see Setup URL and Setup Code, finish /setup in the browser, then copy the server URL for phones."
      ]
    },
    "windows": {
      "title": "Windows PC",
      "steps": [
        "Open PowerShell and cd into your KNOT folder.",
        "Run: .\\scripts\\knot-cli.ps1",
        "If Windows blocks the script, you may need: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned",
        "Pick Docker (1), Railway (2), or bare metal (3).",
        "When you see Setup URL and Setup Code, finish /setup in the browser, then copy the server URL for phones."
      ]
    },
    "cloud_hosting": {
      "title": "Cloud hosting (Railway)",
      "steps": [
        "Install the Railway CLI (brew install railway, npm install -g @railway/cli, or the install script from railway.app).",
        "Run railway login once.",
        "From the KNOT folder run ./scripts/knot-cli (or the Windows script) and choose option 2.",
        "When deployment finishes, open the HTTPS Setup URL shown in the terminal.",
        "Find Setup Code: OWNER-XXXXXXXX in railway logs if it is not printed automatically.",
        "Paste the Railway HTTPS URL into the mobile app — not localhost."
      ]
    }
  },
  "localhost_and_phones": {
    "title": "Why phones usually cannot use localhost",
    "summary": "On a phone, localhost means the phone itself — not your Mac or Windows PC. If Knot is running on another computer, the mobile app needs that computer's real address on the network or a secure tunnel URL.",
    "plain_language": [
      "localhost on the host computer is fine while you are testing in a desktop browser on that same computer.",
      "A phone or tablet must use a URL that reaches the host over Wi‑Fi, Tailscale, a domain, or a cloud host.",
      "If the URL works in the host browser but not on the phone, you almost always need a different URL for the phone."
    ]
  },
  "https_tailscale_hosted": {
    "title": "HTTPS, Tailscale, and hosted URLs",
    "summary": "Phones need a URL they can actually open. HTTPS is required for microphone (voice) on real mobile devices.",
    "options": [
      {
        "id": "domain_https",
        "title": "Your own domain with HTTPS",
        "body": "Point DNS at your server and use Docker Compose with a real domain. The setup utility configures KNOT_DOMAIN; Caddy provisions certificates."
      },
      {
        "id": "tailscale",
        "title": "Tailscale Serve",
        "body": "Install Tailscale on the host and family phones (same tailnet). Run tailscale serve --bg 8787 and use the https://….ts.net URL on phones. Good for home trips without public DNS."
      },
      {
        "id": "railway_hosted",
        "title": "Hosted URL (Railway)",
        "body": "Railway gives you an https://….up.railway.app URL. Use that in the mobile app after setup completes."
      }
    ],
    "voice_note": "Voice queries need a secure context (HTTPS). Plain HTTP on a real phone will block the microphone even if the page otherwise loads."
  },
  "mobile_app": {
    "title": "Using the URL in the mobile app",
    "steps": [
      "Open Knot on iPhone, iPad, or Android.",
      "Choose Connect to a server (Server Mode).",
      "Paste the full server URL (must start with https://, or http://localhost only for simulator testing on the same machine).",
      "Tap Connect. The app remembers the URL for next time.",
      "If connection fails, use Setup Notes in the app or this page's troubleshooting section."
    ],
    "url_rules": [
      "Production phones: use https://",
      "Local simulator on the same Mac: http://localhost is allowed for development",
      "Never paste an API key into the server URL field — only the web address"
    ]
  },
  "api_keys": {
    "title": "API keys, safely explained",
    "summary": "Knot may ask for an AI provider API key during setup or in Settings when you turn on concierge features. That key is yours — it unlocks AI helpers inside your trip workspace.",
    "rules": [
      "Create the key on the official provider website (OpenAI, Anthropic, Google, etc.).",
      "Paste it only into Knot's official setup field or trusted local configuration on your server.",
      "Do not paste API keys into public AI chats, screenshots, Discord, or text messages.",
      "If a key is exposed, revoke it in the provider dashboard and create a new one.",
      "This help page will never ask you to share your API key in chat."
    ]
  },
  "troubleshooting": [
    {
      "problem": "Could not connect to the server.",
      "likely_causes": [
        "Knot is not running on the host computer.",
        "The server URL is wrong or missing https://",
        "The phone cannot reach the host computer's network.",
        "The user used localhost on a phone, but Knot is running on a different computer.",
        "The server needs HTTPS or a secure tunnel for the current workflow."
      ],
      "fixes": [
        "Confirm Knot is running on the host computer.",
        "Open the server URL in a browser on the host computer.",
        "If using a phone, test the URL in the phone's browser.",
        "Use the HTTPS Tailscale or hosted URL instead of localhost for phones and tablets.",
        "Copy the JSON AI help prompt from the app and ask a trusted helper to diagnose it."
      ]
    },
    {
      "problem": "The paste button does not fill the server URL.",
      "likely_causes": [
        "The clipboard is empty.",
        "The simulator or mobile OS did not share clipboard contents.",
        "The copied text is not plain text."
      ],
      "fixes": [
        "Copy the full URL again.",
        "Tap the URL field and type the URL manually.",
        "On a simulator, use the simulator clipboard tools or type the URL directly.",
        "Make sure the copied value starts with http:// or https://."
      ]
    },
    {
      "problem": "The setup utility asks for an API key.",
      "likely_causes": [
        "Knot needs access to an AI provider for AI-powered features.",
        "The key has not been configured yet."
      ],
      "fixes": [
        "Use the official provider website to create an API key.",
        "Paste the key only into the official Knot setup field or trusted local configuration.",
        "Do not paste the key into public AI chats, screenshots, or messages.",
        "If a key is exposed, revoke it in the provider dashboard and create a new one."
      ]
    },
    {
      "problem": "Voice does not work.",
      "likely_causes": [
        "The app is using plain HTTP on a real mobile device.",
        "The browser or web view requires a secure context for microphone access."
      ],
      "fixes": [
        "Use an HTTPS URL.",
        "Use Tailscale Serve or a hosted server URL.",
        "Confirm microphone permission is enabled on the mobile device."
      ]
    }
  ],
  "copyable_ai_prompts": [
    {
      "id": "general-setup-helper",
      "title": "General setup helper prompt",
      "safe_to_share": true,
      "contains_secrets": false,
      "text": "I am setting up Knot, the trip command center. Please walk me through the setup step by step. My host computer is: [Mac / Windows PC / Linux / server]. My mobile device is: [iPhone / iPad / Android phone / Android tablet]. I am trying to run one of these commands from the KNOT folder: macOS or Linux: ./scripts/knot-cli. Windows PowerShell: .\\scripts\\knot-cli.ps1. Please explain what I should click or type, what an API key is if Knot asks for one, and how to find the final server URL I need to paste into the mobile app. Do not ask me to share API keys, passwords, private tokens, or private setup codes. Official setup guide: https://knot.llmtech.net/setupcli"
    },
    {
      "id": "connection-error-helper-json-template",
      "title": "Connection error helper JSON template",
      "safe_to_share": true,
      "contains_secrets": false,
      "json_template": {
        "ask": "Please help me diagnose why the Knot mobile app cannot reach this server URL. Explain the steps for a non-technical user. Do not ask me to share API keys, passwords, or private tokens.",
        "attempted_server_url": "[paste the server URL shown in the app]",
        "contains_secrets": false,
        "manual_url": "https://knot.llmtech.net/setupcli",
        "product": "Knot",
        "safe_to_share": true,
        "screen": "Server Mode connection error",
        "user_context": {
          "goal": "Connect the mobile app to a running Knot server",
          "host_computer": "Mac, Windows PC, Linux, or server",
          "mobile_device": "iOS or Android"
        },
        "visible_error": "Could not connect to the server."
      }
    }
  ],
  "website_content_requirements": {
    "must_include": [
      "A plain-language explanation of Server Mode and Cloud Mode.",
      "A clear warning that API keys are private.",
      "Mac/Linux and Windows commands.",
      "A section explaining why phones usually cannot use localhost from another computer.",
      "A section explaining HTTPS, Tailscale, and hosted URLs.",
      "Troubleshooting for connection errors.",
      "A copyable AI help prompt that is safe to share.",
      "A link back to the mobile app flow or QR-friendly instructions if available."
    ],
    "must_not_include": [
      "Requests for the user's API key in chat.",
      "Instructions to post private tokens publicly.",
      "Mac-only setup language.",
      "Assumptions that the user knows terminal terminology."
    ],
    "recommended_page_sections": [
      "Start Here",
      "Choose Your Setup Path",
      "Mac or Linux",
      "Windows PC",
      "Cloud Hosting",
      "Using the URL in the Mobile App",
      "API Keys, Safely Explained",
      "Troubleshooting",
      "Copy This Prompt for Help"
    ]
  },
  "app_review_notes": {
    "positioning": "This manual supports the in-app Server Mode setup flow and recovery screens.",
    "review_screenshot_candidates": [
      "Server URL entry",
      "Connection error with JSON help prompt",
      "Edit Server recovery preserving URL",
      "Cloud Mode provider list"
    ]
  }
}