forkit-connect 0.1.29 → 0.1.31

package/QUICKSTART.md

@@ -20,28 +20,24 @@ export PATH="$HOME/.local/bin:$PATH"
 ## Recommended First Run
 
 ```bash
-forkit-connect init
 forkit-connect login
-forkit-connect workspace select
-forkit-connect runtime register
+forkit-connect workspace status
 forkit-connect scan
 forkit-connect inbox
-forkit-connect changes
+forkit-connect runtime status
 forkit-connect status
-forkit-connect start
 ```
 
 ## What Each Step Does
 
-- `init` creates local Connect identity and privacy posture metadata.
 - `login` completes the device-login flow against Forkit.dev.
-- `workspace select` binds the governed workspace/project lane when the account supports it.
-- `runtime register` creates or reuses a governed runtime for the current repo/worktree and stores its runtime key locally.
+- `workspace status` shows whether this account already has governed workspace/project scope.
 - `scan` detects supported local runtimes and AI models.
 - `inbox` shows what is ready to connect, what needs confirmation, and what is already connected.
-- `changes` shows the local evidence trail, runtime signal history, and anything still waiting to sync.
+- `runtime status` shows runtime connection and signal posture.
 - `status` summarizes readiness, daemon state, discovery counts, and next recommended action.
-- `start` launches the daemon loop for continued runtime observation, check-ins, and sync preparation.
+
+Advanced users can run `forkit-connect init` when they explicitly want to prepare or reset local identity and privacy posture before login.
 
 ## Useful Next Commands
 

package/README.md

@@ -31,7 +31,9 @@ Published npm install:
 ```bash
 npx forkit-connect --help
 npm install -g forkit-connect
-forkit-connect status
+forkit-connect login
+forkit-connect scan
+forkit-connect inbox
 ```
 
 From `integrations/connect`:
@@ -57,8 +59,8 @@ If `~/.local/bin` is already on your `PATH`, the command is immediately accessib
 
 ## Public Commands
 
-- `forkit-connect init` — initialize local Connect identity and privacy posture
 - `forkit-connect login` — link this device to Forkit.dev with the device flow
+- `forkit-connect init` — optional advanced local identity and privacy posture setup
 - `forkit-connect scan` — discover local runtimes and AI models
 - `forkit-connect inbox` — review the Smart Registration Inbox
 - `forkit-connect connect <modelNameOrDiscoveryHash>` — prepare or sync a passport draft for a detected model
@@ -125,7 +127,7 @@ npm install /absolute/path/to/forkit-connect-0.1.24.tgz
 npx forkit-connect --help
 npx forkit-connect status
 npx forkit-connect inbox
-npx forkit-connect init
+npx forkit-connect login
 ```
 
 For a user-space Ubuntu install that creates a stable command path, prefer `pnpm run install:ubuntu`.

package/dist/cli.js

@@ -94,6 +94,19 @@ const PUBLIC_COMMANDS = [
     ['ignore', 'Deny one detected local model on this device'],
     ['doctor', 'Run local environment diagnostics'],
 ];
+const START_HERE_COMMANDS = [
+    ['forkit-connect login', 'Pair this machine with your Forkit.dev account'],
+    ['forkit-connect workspace status', 'Confirm the active workspace and project scope'],
+    ['forkit-connect scan', 'Find local models, agents, and runtimes'],
+    ['forkit-connect inbox', 'Review what should become a Passport'],
+    ['forkit-connect runtime status', 'Check runtime connection and signal posture'],
+];
+const EVERYDAY_COMMANDS = [
+    ['forkit-connect status', 'One-line account, device, queue, and scope health'],
+    ['forkit-connect start', 'Open the guided local launcher'],
+    ['forkit-connect sync', 'Flush queued metadata and lifecycle evidence'],
+    ['forkit-connect doctor', 'Diagnose local setup issues'],
+];
 const ADVANCED_COMMAND_GROUPS = [
     ['connect', 'Model connection, runtime review, and handoff utilities'],
     ['runtime', 'Repo-scoped runtime observation and journaling utilities'],
@@ -118,28 +131,32 @@ const ADVANCED_COMMAND_GROUPS = [
     ['notify', 'Notification preview and delivery controls'],
 ];
 function usage() {
-    printCliHeader('CLI', 'Precise local review, runtime detection, and registration handoff.');
-    console.log(cliKeyLine('usage', 'forkit-connect <command> [options]'));
-    console.log(cliKeyLine('scope', 'forkit-connect workspace <list|select|create|status>'));
-    console.log(cliKeyLine('runtime', 'forkit-connect runtime <register|review|status>'));
-    printCliSection('Core');
-    for (const [command, description] of PUBLIC_COMMANDS) {
-        console.log(cliKeyLine(command, description));
+    printCliHeader('CLI', 'Local AI runtime passporting without copying model data.');
+    console.log(cliKeyLine('best first run', 'forkit-connect login'));
+    console.log(cliKeyLine('privacy model', 'metadata only; secrets stay local'));
+    console.log(cliKeyLine('advanced map', 'forkit-connect --advanced-help'));
+    printCliSection('Start Here');
+    for (const [command, description] of START_HERE_COMMANDS) {
+        console.log(cliCommandLine(command, description));
+    }
+    printCliSection('Daily Ops');
+    for (const [command, description] of EVERYDAY_COMMANDS) {
+        console.log(cliCommandLine(command, description));
     }
     printCliSection('Flags');
     console.log(cliKeyLine('--json', 'Machine-readable output when supported'));
     console.log(cliKeyLine('--version', 'Print the Forkit Connect CLI version'));
-    console.log(cliKeyLine('--all-ready', 'Register every ready local model in the current scope'));
-    console.log(cliKeyLine('--model', 'Model name used by register'));
-    console.log(cliKeyLine('--entrypoint', 'Relative project path used by runtime register'));
     console.log(cliKeyLine('--dry-run', 'Show inferred runtime payload without creating it'));
-    console.log(cliKeyLine('--no-browser', 'Do not auto-open browser verification during login'));
     console.log(cliKeyLine('--plain', 'Disable the interactive terminal table surface'));
-    console.log(cliKeyLine('--advanced-help', 'Show internal and engineering commands'));
+    console.log(cliKeyLine('--advanced-help', 'Show the full engineering command map'));
 }
 function advancedUsage() {
-    usage();
-    printCliSection('Advanced');
+    printCliHeader('Advanced CLI', 'Full engineering map for automation, C2, and release operations.');
+    printCliSection('Public Commands');
+    for (const [command, description] of PUBLIC_COMMANDS) {
+        console.log(cliKeyLine(command, description));
+    }
+    printCliSection('Advanced Routes');
     console.log(cliKeyLine('connect', 'forkit-connect connect <modelNameOrDiscoveryHash>'));
     console.log(cliKeyLine('connect', 'forkit-connect connect <start|init|status|inbox|services|permissions|handoff|evolution review|runtime review|runtime status>'));
     console.log(cliKeyLine('targets', 'forkit-connect runtime target <add|list|remove|status>'));
@@ -156,6 +173,103 @@ function advancedUsage() {
     console.log(cliKeyLine('--api-key', 'Runtime signal API key used by runtime observe'));
     console.log(cliKeyLine('--draft-only', 'Allow private continuation when governed publish is blocked'));
 }
+function commandUsage(command) {
+    switch (command) {
+        case 'init':
+            printCliHeader('Init', 'Prepare local Connect identity and privacy posture without signing in.');
+            console.log(cliKeyLine('usage', 'forkit-connect init'));
+            console.log(cliKeyLine('when', 'Optional local setup; most users should start with forkit-connect login'));
+            console.log(cliKeyLine('privacy', 'Creates local metadata state only; no model files, prompts, outputs, or secrets are uploaded'));
+            console.log(cliKeyLine('next', 'forkit-connect login'));
+            return true;
+        case 'login':
+            printCliHeader('Login', 'Pair this machine with Forkit.dev through browser device approval.');
+            console.log(cliKeyLine('usage', 'forkit-connect login [--no-browser]'));
+            console.log(cliKeyLine('opens', `${DEFAULT_BASE_URL}/connect/verify`));
+            console.log(cliKeyLine('stores', 'Session reference in secure local storage where available'));
+            console.log(cliKeyLine('privacy', 'No model files, prompts, outputs, or secrets are uploaded'));
+            console.log(cliKeyLine('--no-browser', 'Print the approval URL instead of opening a browser'));
+            return true;
+        case 'logout':
+            printCliHeader('Logout', 'Remove the stored Forkit.dev session from this device.');
+            console.log(cliKeyLine('usage', 'forkit-connect logout'));
+            console.log(cliKeyLine('keeps', 'Local discovery state and reviewed metadata remain on this device'));
+            return true;
+        case 'changes':
+            printCliHeader('Changes', 'Review local evidence, runtime signal history, and queued metadata.');
+            console.log(cliKeyLine('usage', 'forkit-connect changes [--json] [--limit <count>]'));
+            console.log(cliKeyLine('safe', 'Read-only local review; does not publish or sync by itself'));
+            return true;
+        case 'start':
+            printCliHeader('Start', 'Open the guided launcher or run the local daemon loop.');
+            console.log(cliKeyLine('usage', 'forkit-connect start [--plain] [--foreground]'));
+            console.log(cliKeyLine('plain', 'Use --plain for non-interactive terminals'));
+            console.log(cliKeyLine('foreground', 'Use --foreground to run sync loop in this terminal'));
+            return true;
+        case 'stop':
+            printCliHeader('Stop', 'Stop the local Connect daemon without deleting local state.');
+            console.log(cliKeyLine('usage', 'forkit-connect stop'));
+            console.log(cliKeyLine('safe', 'Does not revoke account access or remove local metadata'));
+            return true;
+        case 'sync':
+            printCliHeader('Sync', 'Flush approved metadata-only queue items to Forkit.dev.');
+            console.log(cliKeyLine('usage', 'forkit-connect sync [--json]'));
+            console.log(cliKeyLine('requires', 'Signed-in account and approved local queue items'));
+            return true;
+        case 'scan':
+        case 'discover':
+            printCliHeader('Scan', 'Discover local models, agents, and runtimes with metadata-only checks.');
+            console.log(cliKeyLine('usage', 'forkit-connect scan [--json] [--dry-run]'));
+            console.log(cliKeyLine('checks', 'Ollama, LM Studio, OpenAI-compatible local servers, and local model folders'));
+            console.log(cliKeyLine('next', 'forkit-connect inbox'));
+            return true;
+        case 'inbox':
+            printCliHeader('Inbox', 'Review detected records before creating or connecting Passports.');
+            console.log(cliKeyLine('usage', 'forkit-connect inbox [--json]'));
+            console.log(cliKeyLine('safe', 'Review-only by default; create/publish actions are explicit'));
+            return true;
+        case 'status':
+            printCliHeader('Status', 'Show account, device, queue, runtime, and scope posture.');
+            console.log(cliKeyLine('usage', 'forkit-connect status [--json]'));
+            console.log(cliKeyLine('next', 'If session is expired, run forkit-connect login'));
+            return true;
+        case 'workspace':
+            printCliHeader('Workspace', 'Manage governed workspace and project scope for Signal and Protocol accounts.');
+            console.log(cliKeyLine('usage', 'forkit-connect workspace status [--json]'));
+            console.log(cliKeyLine('usage', 'forkit-connect workspace select --workspace <id> --project <id>'));
+            console.log(cliKeyLine('note', 'Origin remains personal/public; governed scope starts with Signal'));
+            return true;
+        case 'runtime':
+            printCliHeader('Runtime', 'Review and connect local runtime posture without uploading runtime data.');
+            console.log(cliKeyLine('usage', 'forkit-connect runtime status [--json]'));
+            console.log(cliKeyLine('usage', 'forkit-connect runtime review [--json]'));
+            console.log(cliKeyLine('privacy', 'Metadata-only status, heartbeat, and lifecycle evidence'));
+            return true;
+        case 'doctor':
+            printCliHeader('Doctor', 'Diagnose local setup, secure storage, runtime availability, and session truth.');
+            console.log(cliKeyLine('usage', 'forkit-connect doctor [--json]'));
+            console.log(cliKeyLine('healthy', 'PASS/WARN/FAIL checks with clear next action'));
+            return true;
+        case 'update-check':
+            printCliHeader('Update Check', 'Compare npm CLI and desktop installer release channels.');
+            console.log(cliKeyLine('usage', 'forkit-connect update-check'));
+            console.log(cliKeyLine('cli', 'Uses the public npm forkit-connect latest version'));
+            console.log(cliKeyLine('desktop', 'Uses Forkit Connect desktop installer metadata separately'));
+            return true;
+        case 'connect':
+            printCliHeader('Connect', 'Prepare or sync a detected model into a passport-ready flow.');
+            console.log(cliKeyLine('usage', 'forkit-connect connect <modelNameOrDiscoveryHash>'));
+            console.log(cliKeyLine('review', 'Use forkit-connect inbox first to choose the right target'));
+            return true;
+        case 'register':
+            printCliHeader('Register', 'Register ready local models through the reviewed Connect flow.');
+            console.log(cliKeyLine('usage', 'forkit-connect register <modelNameOrDiscoveryHash>'));
+            console.log(cliKeyLine('safe', 'Governed accounts require workspace/project scope before registration'));
+            return true;
+        default:
+            return false;
+    }
+}
 function showUsage() {
     if (hasFlag('--advanced-help')) {
         advancedUsage();
@@ -879,6 +993,9 @@ function cliTag(label, tone = 'muted') {
 function cliKeyLine(label, value) {
     return `  ${cliDim(`${label}`.padEnd(CLI_LABEL_WIDTH, ' '))} ${value}`;
 }
+function cliCommandLine(command, value) {
+    return `  ${cliDim(command.padEnd(34, ' '))} ${value}`;
+}
 function printCliHeader(title, subtitle) {
     console.log(`[forkit-connect] ${cliBold(title)}`);
     if (subtitle) {
@@ -2593,6 +2710,25 @@ function printTrayStatus(status, menu) {
 async function run() {
     const args = process.argv.slice(2);
     const command = args[0];
+    if (!command) {
+        showUsage();
+        return;
+    }
+    if (command === 'version' || command === '--version' || command === '-v') {
+        console.log((0, update_1.getCurrentConnectVersion)());
+        return;
+    }
+    if (isHelpCommand(command)) {
+        showUsage();
+        return;
+    }
+    if (hasFlag('--help') || hasFlag('-h')) {
+        if (!commandUsage(command)) {
+            showUsage();
+            process.exitCode = 2;
+        }
+        return;
+    }
     const service = new service_1.ConnectV1Service();
     const sessionRef = getArg('--session-ref');
     const workspaceId = getArg('--workspace');
@@ -2607,18 +2743,6 @@ async function run() {
     if (sessionRef !== null) {
         service.setSessionRef(sessionRef);
     }
-    if (!command) {
-        showUsage();
-        return;
-    }
-    if (command === 'version' || command === '--version' || command === '-v') {
-        console.log((0, update_1.getCurrentConnectVersion)());
-        return;
-    }
-    if (isHelpCommand(command)) {
-        showUsage();
-        return;
-    }
     const runPublicConnectInit = () => {
         printConnectInit(service.initializeConnectIdentity());
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forkit-connect",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "description": "Forkit Connect Local Engine - The Global AI Governance Fabric",
   "license": "MIT",
   "main": "dist/index.js",