@easonwumac/computer-linker 0.1.8 → 0.1.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (14) hide show
  1. package/CHANGELOG.md +33 -0
  2. package/README.md +84 -78
  3. package/dist/capabilities.d.ts +1 -1
  4. package/dist/capabilities.js +11 -3
  5. package/dist/chatgpt.js +3 -3
  6. package/dist/cli.js +89 -14
  7. package/docs/architecture.md +67 -23
  8. package/docs/chatgpt-setup.md +25 -19
  9. package/docs/client-recipes.md +25 -18
  10. package/docs/getting-started.md +187 -0
  11. package/docs/manual-test-plan.md +48 -25
  12. package/docs/product-spec.md +5 -4
  13. package/docs/release-checklist.md +12 -10
  14. package/package.json +2 -1
package/CHANGELOG.md CHANGED
@@ -5,6 +5,39 @@ All notable changes to Computer Linker will be documented in this file.
5
5
  This project follows a small pre-1.0 changelog: breaking contract changes are
6
6
  called out even when the package version is still `0.x`.
7
7
 
8
+ ## 0.1.10 - 2026-06-27
9
+
10
+ ### Added
11
+
12
+ - Added `computer-linker here` as the short daily startup command for exposing
13
+ the current folder, equivalent to `computer-linker start .`.
14
+ - Added a step-by-step getting started tutorial for install checks, local MCP
15
+ clients, public tunnels, agent instructions, daily commands, and
16
+ troubleshooting.
17
+ - Added an implementation module map to the architecture docs so CLI, config,
18
+ MCP transport, operation dispatch, providers, client helpers, tunnels, and
19
+ release tooling have clearer boundaries.
20
+
21
+ ### Changed
22
+
23
+ - README, client recipes, ChatGPT compatibility setup, manual test docs, and
24
+ CLI help now lead with `here` for current-folder setup while keeping
25
+ `start <folder>` for explicit paths and existing no-argument server startup.
26
+
27
+ ## 0.1.9 - 2026-06-27
28
+
29
+ ### Added
30
+
31
+ - Added `npm run release -- --otp <code>` as the one-command local npm publish
32
+ path, wrapping publish, tag creation, registry verification, published CLI
33
+ smoke, and Git push.
34
+
35
+ ### Changed
36
+
37
+ - README, release checklist, and release wrapper help now recommend the
38
+ one-command release path while keeping check, dry-run, and lower-level
39
+ publish commands for diagnostics.
40
+
8
41
  ## 0.1.8 - 2026-06-27
9
42
 
10
43
  ### Changed
package/README.md CHANGED
@@ -19,46 +19,48 @@ Install the CLI, expose one folder, and keep the server running:
19
19
  ```powershell
20
20
  npm install -g @easonwumac/computer-linker
21
21
  computer-linker check
22
- computer-linker start C:\Projects\my-app
22
+ cd C:\Projects\my-app
23
+ computer-linker here
23
24
  ```
24
-
25
- Leave that terminal running. In another terminal, copy the MCP client settings
25
+
26
+ Leave that terminal running. In another terminal, copy the MCP client settings
26
27
  and verify the connection:
27
28
 
28
29
  ```powershell
29
30
  computer-linker client setup
30
- computer-linker diagnose client
31
- ```
32
-
33
- `start <folder>` creates config, owner token, and a workspace entry when
34
- needed. The workspace name defaults to the folder name. By default it enables
35
- file edits plus approved project commands. Use `--read-only` for inspection
36
- only or `--full-trust` only for folders where Codex and screen capture are
37
- intended.
31
+ computer-linker diagnose client
32
+ ```
33
+
34
+ `here` exposes the current folder. From another folder, use
35
+ `computer-linker start C:\Projects\my-app` instead. Both commands create
36
+ config, owner token, and a workspace entry when needed. The workspace name
37
+ defaults to the folder name. By default it enables file edits plus approved
38
+ project commands. Use `--read-only` for inspection only or `--full-trust` only
39
+ for folders where Codex and screen capture are intended.
38
40
 
39
41
  From this source checkout, use the same flow through the development runner:
40
42
 
41
- ```powershell
42
- npm install
43
- npm run dev -- quickstart C:\Projects\my-app
44
- npm run dev -- start C:\Projects\my-app
45
- ```
46
-
47
- Use `client setup --show-token` only on a trusted local setup screen when the
48
- client needs the bearer token.
49
-
50
- What `start <folder>` does:
51
-
52
- - creates config, owner token, and workspace entry when needed
53
- - uses the folder name as the workspace name by default
54
- - updates an existing workspace for the same folder instead of duplicating it
55
- - starts the local MCP server at `http://127.0.0.1:3939/mcp`
56
- - runs a startup check against health, JSON API, MCP initialize, tools/list,
57
- `get_computer_info`, `computer_operation`, and operation history
58
-
59
- `start <folder>` and `setup <folder>` default to normal coding access: file
60
- edits plus approved project commands. Use `--read-only` for inspection-only
61
- access, or `--full-trust` only where Codex and screen capture are intended. Add
43
+ ```powershell
44
+ npm install
45
+ npm run dev -- quickstart C:\Projects\my-app
46
+ npm run dev -- start C:\Projects\my-app
47
+ ```
48
+
49
+ Use `client setup --show-token` only on a trusted local setup screen when the
50
+ client needs the bearer token.
51
+
52
+ What `here` and `start <folder>` do:
53
+
54
+ - creates config, owner token, and workspace entry when needed
55
+ - uses the folder name as the workspace name by default
56
+ - updates an existing workspace for the same folder instead of duplicating it
57
+ - starts the local MCP server at `http://127.0.0.1:3939/mcp`
58
+ - runs a startup check against health, JSON API, MCP initialize, tools/list,
59
+ `get_computer_info`, `computer_operation`, and operation history
60
+
61
+ `here`, `start <folder>`, and `setup <folder>` default to normal coding access: file
62
+ edits plus approved project commands. Use `--read-only` for inspection-only
63
+ access, or `--full-trust` only where Codex and screen capture are intended. Add
62
64
  `--codex` or `--screen` only for folders where those abilities are intended.
63
65
  When shell or Codex access is enabled, Computer Linker also creates a default
64
66
  execution policy with command allowlists and runtime/output limits.
@@ -82,8 +84,8 @@ use `computer-linker help advanced` for service, config, API, and compatibility
82
84
  commands. ChatGPT-specific setup exports are compatibility helpers under
83
85
  `computer-linker help chatgpt`; prefer the generic MCP client commands first.
84
86
 
85
- `start` is local-only unless you pass `--tunnel cloudflare`, `--tunnel
86
- tailscale`, or `--tunnel openai`.
87
+ `here` and `start <folder>` are local-only unless you pass `--tunnel
88
+ cloudflare`, `--tunnel tailscale`, or `--tunnel openai`.
87
89
 
88
90
  ## Expose To Cloud Clients
89
91
 
@@ -94,10 +96,11 @@ OpenAI Secure MCP Tunnel does not create a public URL. Create a tunnel in the
94
96
  OpenAI Platform tunnel settings, set an API key with Tunnels Read+Use
95
97
  permission, then run:
96
98
 
97
- ```powershell
98
- $env:CONTROL_PLANE_API_KEY = "sk-..."
99
- computer-linker start C:\Projects\my-app --tunnel openai --tunnel-id tunnel_...
100
- ```
99
+ ```powershell
100
+ $env:CONTROL_PLANE_API_KEY = "sk-..."
101
+ cd C:\Projects\my-app
102
+ computer-linker here --tunnel openai --tunnel-id tunnel_...
103
+ ```
101
104
 
102
105
  In ChatGPT connector settings, choose the tunnel option and select or paste the
103
106
  `tunnel_...` id. The target MCP path remains the local server path `/mcp`.
@@ -117,9 +120,10 @@ your Desktop for executables. To use a pinned binary instead, set
117
120
 
118
121
  Tailscale Funnel:
119
122
 
120
- ```powershell
121
- computer-linker start C:\Projects\my-app --tunnel tailscale
122
- ```
123
+ ```powershell
124
+ cd C:\Projects\my-app
125
+ computer-linker here --tunnel tailscale
126
+ ```
123
127
 
124
128
  You do not need to type `https://<machine>.<tailnet>.ts.net` up front.
125
129
  Computer Linker detects the Funnel URL from `tailscale funnel` output or
@@ -129,15 +133,17 @@ Funnel as enabled; plain Tailscale DNS or Serve remains tailnet-only.
129
133
 
130
134
  Cloudflare quick tunnel:
131
135
 
132
- ```powershell
133
- computer-linker start C:\Projects\my-app --tunnel cloudflare
134
- ```
136
+ ```powershell
137
+ cd C:\Projects\my-app
138
+ computer-linker here --tunnel cloudflare
139
+ ```
135
140
 
136
141
  Cloudflare hostname you already own:
137
142
 
138
- ```powershell
139
- computer-linker start C:\Projects\my-app --url https://mcp.your-domain.com --tunnel cloudflare
140
- ```
143
+ ```powershell
144
+ cd C:\Projects\my-app
145
+ computer-linker here --url https://mcp.your-domain.com --tunnel cloudflare
146
+ ```
141
147
 
142
148
  Tunnel commands enable `publicMcpOnly` automatically. Public-host requests to
143
149
  `/api` and `/healthz` return 404 from Computer Linker, leaving `/mcp` as the
@@ -307,13 +313,14 @@ computer-linker workspace update app --no-shell --no-screen
307
313
  computer-linker workspace remove app
308
314
  ```
309
315
 
310
- When `--id` or `--name` is omitted, Computer Linker derives it from the folder
311
- name. Direct `workspace add` scopes default to read-only with screen capture
312
- disabled. Add `--write`, `--shell`, `--codex`, or `--screen` separately only
313
- where needed. For daily setup, prefer `computer-linker start <folder>`; it
314
- creates a normal coding workspace and default execution policy automatically.
315
- Advanced `workspace add/update` flows leave policy management explicit through
316
- `config policy`.
316
+ When `--id` or `--name` is omitted, Computer Linker derives it from the folder
317
+ name. Direct `workspace add` scopes default to read-only with screen capture
318
+ disabled. Add `--write`, `--shell`, `--codex`, or `--screen` separately only
319
+ where needed. For daily setup, prefer `computer-linker here` inside the folder,
320
+ or `computer-linker start <folder>` from somewhere else; both create a normal
321
+ coding workspace and default execution policy automatically. Advanced
322
+ `workspace add/update` flows leave policy management explicit through `config
323
+ policy`.
317
324
 
318
325
  The config lives at:
319
326
 
@@ -472,25 +479,23 @@ npm ci
472
479
  npm run product:check
473
480
  ```
474
481
 
475
- For npm publishing, use the local release wrapper instead of hand-running every
476
- step:
477
-
478
- ```bash
479
- npm run release:check
480
- npm run release:dry-run
481
- npm run release:publish -- --create-tag --push --otp <code>
482
+ For npm publishing, use the local release wrapper instead of hand-running every
483
+ step:
484
+
485
+ ```bash
486
+ npm run release -- --otp <code>
482
487
  ```
483
-
484
- `release:check` runs the local product/public package gates without publishing.
485
- `release:dry-run` runs `npm publish --dry-run` and creates a temporary local
486
- `v<package.version>` tag only for that dry-run when the tag is missing.
487
- `release:publish` requires a clean main/master worktree, a dated changelog
488
- heading, npm login, and a release tag. Pass `--create-tag` to create the tag
489
- on `HEAD`; pass `--push` only when you want the script to push `HEAD` and the
490
- release tag after a successful npm publish. After npm accepts the publish, the
491
- wrapper waits for registry metadata, verifies the npm dist-tag, and runs the
492
- published CLI from a clean temporary directory. Use `npm run release:verify` to
493
- repeat that post-publish check for the current `package.json` version.
488
+
489
+ `release` requires a clean main/master worktree, a dated changelog heading, and
490
+ npm login. It creates `v<package.version>` on `HEAD` when missing, runs npm's
491
+ publish guard, publishes, waits for registry metadata, verifies the npm
492
+ dist-tag, runs the published CLI from a clean temporary directory, then pushes
493
+ `HEAD` and the release tag. Use `npm run release:check` before the final commit
494
+ when you want a non-publishing gate, `npm run release:dry-run` for an npm
495
+ dry-run only, or `npm run release:publish -- --create-tag --push --otp <code>`
496
+ when debugging the lower-level publish wrapper directly. Use `npm run release:verify`
497
+ to repeat the post-publish check for the current `package.json`
498
+ version.
494
499
  On Windows, if `NODE_AUTH_TOKEN` is saved in the User environment but the
495
500
  current shell has not picked it up yet, the release wrapper loads it only into
496
501
  the current release process before running `npm whoami` or `npm publish`.
@@ -541,9 +546,10 @@ The stricter release and publish rules live in
541
546
  Computer Linker is not a remote desktop, a cloud service, or a ChatGPT-specific
542
547
  app. It is a local MCP program that exposes approved computer abilities.
543
548
 
544
- See [docs/product-spec.md](docs/product-spec.md) for the product spec and
545
- [docs/architecture.md](docs/architecture.md) for implementation notes. See
546
- [docs/release-checklist.md](docs/release-checklist.md) for the alpha release
547
- checklist, [docs/manual-test-plan.md](docs/manual-test-plan.md) for dogfooding,
548
- and [SECURITY.md](SECURITY.md) for the current security model. Public
549
- contribution and issue guidelines are in [CONTRIBUTING.md](CONTRIBUTING.md).
549
+ See [docs/getting-started.md](docs/getting-started.md) for the step-by-step
550
+ tutorial, [docs/product-spec.md](docs/product-spec.md) for the product spec,
551
+ and [docs/architecture.md](docs/architecture.md) for implementation notes. See
552
+ [docs/release-checklist.md](docs/release-checklist.md) for the alpha release
553
+ checklist, [docs/manual-test-plan.md](docs/manual-test-plan.md) for dogfooding,
554
+ and [SECURITY.md](SECURITY.md) for the current security model. Public
555
+ contribution and issue guidelines are in [CONTRIBUTING.md](CONTRIBUTING.md).
package/dist/capabilities.d.ts CHANGED
@@ -40,7 +40,7 @@ export interface StartupReadinessCheck {
40
40
  detail?: string;
41
41
  }
42
42
  export interface StartupReadinessMode {
43
- id: "start" | "tunnel-cloudflare" | "tunnel-tailscale" | "tunnel-openai" | "stdio" | "service";
43
+ id: "here" | "start" | "tunnel-cloudflare" | "tunnel-tailscale" | "tunnel-openai" | "stdio" | "service";
44
44
  title: string;
45
45
  command: string;
46
46
  persistent: boolean;
package/dist/capabilities.js CHANGED
@@ -273,6 +273,13 @@ export function startupReadiness(config, service = serviceStatus(config)) {
273
273
  const installDryRunCommand = `computer-linker service install --dry-run --platform ${service.platform}`;
274
274
  const uninstallDryRunCommand = `computer-linker service uninstall --dry-run --platform ${service.platform}`;
275
275
  const modes = [
276
+ {
277
+ id: "here",
278
+ title: "Current-folder MCP server",
279
+ command: "computer-linker here",
280
+ persistent: false,
281
+ useWhen: "Daily foreground setup from inside the folder to expose. Creates or updates the workspace, then starts the local MCP/API server.",
282
+ },
276
283
  {
277
284
  id: "start",
278
285
  title: "Local HTTP MCP server",
@@ -347,8 +354,9 @@ export function startupReadiness(config, service = serviceStatus(config)) {
347
354
  },
348
355
  ];
349
356
  const nextActions = [
350
- "Run `computer-linker start <workspace-path>` for one-command coding setup and startup.",
351
- "Use `computer-linker start <workspace-path> --read-only` when the client should inspect without editing or running project commands.",
357
+ "Run `computer-linker here` inside a project folder for one-command coding setup and startup.",
358
+ "Run `computer-linker start <workspace-path>` from another folder when you need to expose an explicit path.",
359
+ "Use `computer-linker here --read-only` when the client should inspect without editing or running project commands.",
352
360
  "Run `computer-linker doctor --fix` to apply safe local config repairs.",
353
361
  `Run \`${profileBundleCommand}\` to generate persistent startup files for ${service.platform}.`,
354
362
  `Run \`${installDryRunCommand}\` before applying any OS service changes.`,
@@ -501,7 +509,7 @@ function doctorNextActions(blockingReasons, securityFindings, release) {
501
509
  actions.add("Generate or configure an owner token before exposing this machine.");
502
510
  }
503
511
  if (blockingReasons.some((reason) => reason.includes("tunnel provider"))) {
504
- actions.add("Install cloudflared or tailscale, configure a trusted reverse proxy, or use `computer-linker start <workspace-path> --tunnel openai --tunnel-id tunnel_...` with CONTROL_PLANE_API_KEY.");
512
+ actions.add("Install cloudflared or tailscale, configure a trusted reverse proxy, or use `computer-linker here --tunnel openai --tunnel-id tunnel_...` with CONTROL_PLANE_API_KEY.");
505
513
  }
506
514
  if (securityFindings.some((finding) => finding.id === "public-base-url-missing")) {
507
515
  actions.add("Set publicBaseUrl to the stable tunnel origin before OAuth client setup.");
package/dist/chatgpt.js CHANGED
@@ -199,7 +199,7 @@ function chatGptSetupWizard(config, verify, urls) {
199
199
  ? undefined
200
200
  : urls.detectedPublicUrl
201
201
  ? `Optional: run \`computer-linker config set-public-url ${urls.detectedPublicUrl}\` to save it for OAuth and stable reuse.`
202
- : "For first setup, run `computer-linker start <workspace-path> --tunnel tailscale`; for Cloudflare/custom hostnames, pass `--url https://... --tunnel cloudflare`; for ChatGPT Tunnel mode, use `computer-linker start <workspace-path> --tunnel openai --tunnel-id tunnel_...`.",
202
+ : "For first setup, run `computer-linker here --tunnel tailscale` inside the folder; for Cloudflare/custom hostnames, pass `--url https://... --tunnel cloudflare`; for ChatGPT Tunnel mode, use `computer-linker here --tunnel openai --tunnel-id tunnel_...`. From another folder, use `computer-linker start <workspace-path> ...`.",
203
203
  },
204
204
  {
205
205
  id: "mcp_url",
@@ -254,7 +254,7 @@ export function chatGptUrl(config, includeSecret = false, options = {}) {
254
254
  const nextActions = [];
255
255
  if (!mcpServerUrl) {
256
256
  warnings.push("No public HTTPS MCP URL is configured.");
257
- nextActions.push("For first setup, run `computer-linker start <workspace-path> --tunnel tailscale` to auto-save a Funnel URL; for Cloudflare/custom hostnames, pass `--url https://... --tunnel cloudflare`; for ChatGPT Tunnel mode, use `computer-linker start <workspace-path> --tunnel openai --tunnel-id tunnel_...`.");
257
+ nextActions.push("For first setup, run `computer-linker here --tunnel tailscale` inside the folder to auto-save a Funnel URL; for Cloudflare/custom hostnames, pass `--url https://... --tunnel cloudflare`; for ChatGPT Tunnel mode, use `computer-linker here --tunnel openai --tunnel-id tunnel_...`. From another folder, use `computer-linker start <workspace-path> ...`.");
258
258
  }
259
259
  else if (!mcpServerUrl.startsWith("https://")) {
260
260
  warnings.push("ChatGPT requires an https:// MCP URL.");
@@ -535,7 +535,7 @@ function modePermissionCheck(config, mode) {
535
535
  function chatGptNextActions(blockingReasons, warnings, mode) {
536
536
  const actions = new Set();
537
537
  if (blockingReasons.some((reason) => reason.includes("public-base-url"))) {
538
- actions.add("For first setup, run `computer-linker start <workspace-path> --tunnel tailscale` to auto-save a Funnel URL; for Cloudflare/custom hostnames, pass `--url https://... --tunnel cloudflare`; for OpenAI Secure MCP Tunnel, use `computer-linker start <workspace-path> --tunnel openai --tunnel-id tunnel_...`.");
538
+ actions.add("For first setup, run `computer-linker here --tunnel tailscale` inside the folder to auto-save a Funnel URL; for Cloudflare/custom hostnames, pass `--url https://... --tunnel cloudflare`; for OpenAI Secure MCP Tunnel, use `computer-linker here --tunnel openai --tunnel-id tunnel_...`. From another folder, use `computer-linker start <workspace-path> ...`.");
539
539
  }
540
540
  if (blockingReasons.some((reason) => reason.includes("auth"))) {
541
541
  actions.add("Run `computer-linker init` to generate an owner token before exposing the MCP server.");
package/dist/cli.js CHANGED
@@ -78,6 +78,9 @@ async function main(argv) {
78
78
  case "start":
79
79
  await start(args);
80
80
  return;
81
+ case "here":
82
+ await here(args);
83
+ return;
81
84
  case "quickstart":
82
85
  quickstart(args);
83
86
  return;
@@ -146,7 +149,7 @@ function normalizeCommand(command) {
146
149
  throw new Error("connect-profile was removed; use `computer-linker client chatgpt profile` only when ChatGPT asks for connector-specific fields.");
147
150
  if (command === "chatgpt")
148
151
  throw new Error("chatgpt was removed; use `computer-linker client chatgpt <subcommand>` only when ChatGPT asks for connector-specific fields.");
149
- if (command === "init" || command === "start" || command === "quickstart" || command === "status" || command === "check" || command === "self-test" || command === "expose" || command === "tunnel" || command === "service" || command === "workspace" || command === "process" || command === "screen" || command === "doctor" || command === "diagnose" || command === "history" || command === "profile" || command === "client" || command === "config" || command === "setup")
152
+ if (command === "init" || command === "start" || command === "here" || command === "quickstart" || command === "status" || command === "check" || command === "self-test" || command === "expose" || command === "tunnel" || command === "service" || command === "workspace" || command === "process" || command === "screen" || command === "doctor" || command === "diagnose" || command === "history" || command === "profile" || command === "client" || command === "config" || command === "setup")
150
153
  return command;
151
154
  if (command === "version" || command === "--version" || command === "-v")
152
155
  return "version";
@@ -2975,6 +2978,14 @@ async function start(args) {
2975
2978
  throw error;
2976
2979
  }
2977
2980
  }
2981
+ async function here(args) {
2982
+ if (hasHelpFlag(args)) {
2983
+ printHereHelp();
2984
+ return;
2985
+ }
2986
+ assertHereHasNoWorkspacePath(args);
2987
+ await start([".", ...args]);
2988
+ }
2978
2989
  function startupPublicMcpUrlLine(config, tunnelProvider, serverPublicUrl) {
2979
2990
  if (tunnelProvider === "openai") {
2980
2991
  return "Public MCP URL: not used in OpenAI tunnel mode";
@@ -3108,7 +3119,7 @@ function startNextActions(config, options, tunnel) {
3108
3119
  }
3109
3120
  return [
3110
3121
  `Use ${invocationCommand("client", "setup")} to connect a local MCP client.`,
3111
- "For ChatGPT remote access, restart with `computer-linker start <workspace-path> --tunnel openai --tunnel-id tunnel_...`.",
3122
+ "For remote access, restart inside the folder with `computer-linker here --tunnel openai --tunnel-id tunnel_...`; from another folder use `computer-linker start <workspace-path> --tunnel openai --tunnel-id tunnel_...`.",
3112
3123
  config.ownerToken ? "Keep this terminal running while the client is connected." : `Run ${invocationCommand("init")} before exposing this computer.`,
3113
3124
  ];
3114
3125
  }
@@ -3200,9 +3211,9 @@ async function expose(args) {
3200
3211
  server.close();
3201
3212
  }
3202
3213
  }
3214
+ const startValueOptions = new Set(["--tunnel", "--mode", "--tunnel-timeout-ms", "--tunnel-id", "--tunnel-client", "--url", "--id", "--name"]);
3215
+ const startFlagOptions = new Set(["--no-tunnel", "--dev", "--coding", "--full-trust", "--write", "--shell", "--codex", "--screen", "--read-only", "--show-token"]);
3203
3216
  function parseStartOptions(args) {
3204
- const valueOptions = new Set(["--tunnel", "--mode", "--tunnel-timeout-ms", "--tunnel-id", "--tunnel-client", "--url", "--id", "--name"]);
3205
- const flagOptions = new Set(["--no-tunnel", "--dev", "--coding", "--full-trust", "--write", "--shell", "--codex", "--screen", "--read-only", "--show-token"]);
3206
3217
  const positional = [];
3207
3218
  for (let index = 0; index < args.length; index += 1) {
3208
3219
  const arg = args[index];
@@ -3210,13 +3221,13 @@ function parseStartOptions(args) {
3210
3221
  positional.push(arg);
3211
3222
  continue;
3212
3223
  }
3213
- if (valueOptions.has(arg)) {
3224
+ if (startValueOptions.has(arg)) {
3214
3225
  index += 1;
3215
3226
  if (!args[index] || args[index].startsWith("--"))
3216
3227
  throw new Error(`start ${arg} requires a value`);
3217
3228
  continue;
3218
3229
  }
3219
- if (flagOptions.has(arg))
3230
+ if (startFlagOptions.has(arg))
3220
3231
  continue;
3221
3232
  throw new Error(`Unknown start option: ${arg}`);
3222
3233
  }
@@ -3268,6 +3279,23 @@ function parseStartOptions(args) {
3268
3279
  permissionArgs: permissionFlags.canonicalArgs,
3269
3280
  };
3270
3281
  }
3282
+ function assertHereHasNoWorkspacePath(args) {
3283
+ for (let index = 0; index < args.length; index += 1) {
3284
+ const arg = args[index];
3285
+ if (!arg.startsWith("--")) {
3286
+ throw new Error("here does not accept a workspace path; run it inside the folder to expose or use `computer-linker start <workspace-path>` for another folder");
3287
+ }
3288
+ if (startValueOptions.has(arg)) {
3289
+ index += 1;
3290
+ if (!args[index] || args[index].startsWith("--"))
3291
+ throw new Error(`here ${arg} requires a value`);
3292
+ continue;
3293
+ }
3294
+ if (startFlagOptions.has(arg))
3295
+ continue;
3296
+ throw new Error(`Unknown here option: ${arg}`);
3297
+ }
3298
+ }
3271
3299
  function parseTunnelProvider(value, command) {
3272
3300
  if (value === "cloudflare" || value === "tailscale" || value === "openai")
3273
3301
  return value;
@@ -3643,6 +3671,10 @@ function printHelp(args = []) {
3643
3671
  printServeHelp();
3644
3672
  return;
3645
3673
  }
3674
+ if (topic === "here" && rest.length === 0) {
3675
+ printHereHelp();
3676
+ return;
3677
+ }
3646
3678
  if ((topic === "chatgpt" || topic === "client-chatgpt") && rest.length === 0) {
3647
3679
  printChatGptHelp();
3648
3680
  return;
@@ -3755,7 +3787,7 @@ function printServeHelp() {
3755
3787
  "",
3756
3788
  "What it does:",
3757
3789
  " Starts the MCP server without changing workspace config.",
3758
- " For daily use, prefer `computer-linker start <folder>` so setup and server start happen together.",
3790
+ " For daily use, prefer `computer-linker here` or `computer-linker start <folder>` so setup and server start happen together.",
3759
3791
  ]);
3760
3792
  }
3761
3793
  function printCoreHelp() {
@@ -3763,6 +3795,7 @@ function printCoreHelp() {
3763
3795
  "Computer Linker",
3764
3796
  "",
3765
3797
  "Usage:",
3798
+ " computer-linker here",
3766
3799
  " computer-linker start <workspace-path>",
3767
3800
  " computer-linker start <workspace-path> --tunnel openai|tailscale|cloudflare",
3768
3801
  " computer-linker check",
@@ -3772,11 +3805,16 @@ function printCoreHelp() {
3772
3805
  "",
3773
3806
  "First run:",
3774
3807
  " 1. Optional install check: computer-linker check",
3775
- " 2. Start local: computer-linker start C:\\Projects\\my-app",
3808
+ " 2. In your project folder: computer-linker here",
3776
3809
  " 3. Connect client: computer-linker client setup",
3777
3810
  " 4. Check state: computer-linker status",
3778
3811
  "",
3779
3812
  "Cloud client:",
3813
+ " computer-linker here --tunnel openai --tunnel-id tunnel_...",
3814
+ " computer-linker here --tunnel tailscale",
3815
+ " computer-linker here --tunnel cloudflare",
3816
+ "",
3817
+ "From another folder:",
3780
3818
  " computer-linker start C:\\Projects\\my-app --tunnel openai --tunnel-id tunnel_...",
3781
3819
  " computer-linker start C:\\Projects\\my-app --tunnel tailscale",
3782
3820
  " computer-linker start C:\\Projects\\my-app --tunnel cloudflare",
@@ -3785,13 +3823,47 @@ function printCoreHelp() {
3785
3823
  " computer-linker quickstart C:\\Projects\\my-app",
3786
3824
  "",
3787
3825
  "Notes:",
3788
- " <workspace-path> is the folder to expose.",
3789
- " start creates config, token, and a workspace entry when needed, then runs a local startup check.",
3826
+ " here exposes the current folder; start <workspace-path> exposes another folder.",
3827
+ " here and start <workspace-path> create config, token, and a workspace entry when needed, then run a local startup check.",
3790
3828
  " Workspace names default to the folder name.",
3791
- " By default, start allows file edits and approved project commands for normal development work.",
3829
+ " By default, here and start allow file edits and approved project commands for normal development work.",
3792
3830
  " Use --read-only to inspect only; use --full-trust only when Codex and screen capture are intended.",
3793
3831
  " Tokens stay hidden by default; use client setup --show-token only on a trusted local setup screen.",
3794
- " Details: computer-linker help check | computer-linker help start | computer-linker help client setup | computer-linker help advanced",
3832
+ " Details: computer-linker help here | computer-linker help check | computer-linker help start | computer-linker help client setup | computer-linker help advanced",
3833
+ ]);
3834
+ }
3835
+ function printHereHelp() {
3836
+ printCliHelp([
3837
+ "Computer Linker here",
3838
+ "",
3839
+ "Usage:",
3840
+ " computer-linker here",
3841
+ " computer-linker here --read-only",
3842
+ " computer-linker here --full-trust",
3843
+ " computer-linker here --tunnel openai --tunnel-id tunnel_...",
3844
+ " computer-linker here --tunnel tailscale",
3845
+ " computer-linker here --tunnel cloudflare",
3846
+ "",
3847
+ "What it does:",
3848
+ " Exposes the current folder and starts the local HTTP MCP server.",
3849
+ " Equivalent to `computer-linker start .`, with a clearer daily-use name.",
3850
+ " Uses the current folder name as the workspace name unless --name is provided.",
3851
+ " A new workspace defaults to coding mode: file edits plus approved project commands.",
3852
+ "",
3853
+ "Common options:",
3854
+ " --read-only Read/search/history only.",
3855
+ " --full-trust Writes, approved commands, Codex operations, and screen capture.",
3856
+ " --tunnel openai|tailscale|cloudflare",
3857
+ " --name <name> Override the workspace display name.",
3858
+ " --id <id> Override the stable workspace id.",
3859
+ "",
3860
+ "Examples:",
3861
+ " computer-linker here",
3862
+ " computer-linker here --read-only",
3863
+ " computer-linker here --tunnel tailscale",
3864
+ "",
3865
+ "For another folder, use:",
3866
+ " computer-linker start C:\\Projects\\my-app",
3795
3867
  ]);
3796
3868
  }
3797
3869
  function printStartHelp() {
@@ -3809,6 +3881,7 @@ function printStartHelp() {
3809
3881
  "",
3810
3882
  "What it does:",
3811
3883
  " Creates config, owner token, and a workspace entry when needed.",
3884
+ " Use `computer-linker here` when you are already inside the folder to expose.",
3812
3885
  " Uses the folder name as the workspace name unless --name is provided.",
3813
3886
  " Starts the local HTTP MCP server, runs a local startup check, and keeps running until you stop it.",
3814
3887
  " A new workspace defaults to coding mode: file edits plus approved project commands.",
@@ -3994,7 +4067,7 @@ function printSetupHelp() {
3994
4067
  "What it does:",
3995
4068
  " Creates or updates config, owner token, public MCP-only mode, and one workspace entry without starting the server.",
3996
4069
  " Workspace names default to the folder name.",
3997
- " For one-command daily use, prefer `computer-linker start <workspace-path>`.",
4070
+ " For one-command daily use, prefer `computer-linker here` inside the folder or `computer-linker start <workspace-path>` from elsewhere.",
3998
4071
  " New setup entries default to coding mode: file edits plus approved project commands.",
3999
4072
  " Use --read-only to inspect only; use --full-trust only when Codex and screen capture are intended.",
4000
4073
  "",
@@ -4024,7 +4097,7 @@ function printExposeHelp() {
4024
4097
  "",
4025
4098
  "What it does:",
4026
4099
  " Starts an HTTP MCP server and opens a tunnel to it.",
4027
- " `start <workspace-path> --tunnel ...` is the simpler development path.",
4100
+ " `here --tunnel ...` or `start <workspace-path> --tunnel ...` is the simpler development path.",
4028
4101
  "",
4029
4102
  "More help:",
4030
4103
  " computer-linker expose help tailscale",
@@ -4481,6 +4554,7 @@ function printAdvancedHelp() {
4481
4554
  "Advanced Usage:",
4482
4555
  " computer-linker init [--show-token]",
4483
4556
  " computer-linker --version",
4557
+ " computer-linker here [--tunnel cloudflare|tailscale|openai] [--read-only|--full-trust]",
4484
4558
  " computer-linker quickstart [workspace-path] [--tunnel cloudflare|tailscale|openai] [--tunnel-id tunnel_...] [--url https://...] [--write] [--shell] [--codex] [--screen] [--read-only|--full-trust] [--json]",
4485
4559
  " computer-linker serve Start the stdio MCP server",
4486
4560
  " computer-linker serve --transport http",
@@ -4557,6 +4631,7 @@ function printChatGptHelp() {
4557
4631
  " computer-linker client chatgpt files ./chatgpt-config [--mode safe|coding|full] [--url https://...] [--show-token]",
4558
4632
  "",
4559
4633
  "For OpenAI Secure MCP Tunnel, start with:",
4634
+ " computer-linker here --tunnel openai --tunnel-id tunnel_...",
4560
4635
  " computer-linker start <workspace-path> --tunnel openai --tunnel-id tunnel_...",
4561
4636
  ]);
4562
4637
  }
package/docs/architecture.md CHANGED
@@ -55,14 +55,55 @@ local/public MCP URLs, local/public JSON API URLs, and the same redaction
55
55
  default. Capabilities also expose the redacted profile so clients can identify
56
56
  which computer they are connected to.
57
57
 
58
- The previous prototype name was LocalPort. New installs expose only the
59
- `computer-linker` CLI. `LOCALPORT_*` and `x-localport-token` remain config and
60
- HTTP auth compatibility aliases while the product moves to `COMPUTER_LINKER_*`
61
- and `x-computer-linker-token`.
62
-
63
- `get_computer_info` is the public MCP introspection entrypoint. The local
64
- `/api/v1/capabilities` endpoint and compatibility `get_capabilities` tool
65
- expose the fuller implementation diagnostics for local tools, config, security,
58
+ The previous prototype name was LocalPort. New installs expose only the
59
+ `computer-linker` CLI. `LOCALPORT_*` and `x-localport-token` remain config and
60
+ HTTP auth compatibility aliases while the product moves to `COMPUTER_LINKER_*`
61
+ and `x-computer-linker-token`.
62
+
63
+ ## Implementation Module Map
64
+
65
+ The codebase should stay organized around product boundaries instead of client
66
+ or tunnel brands:
67
+
68
+ - CLI orchestration: `src/cli.ts`
69
+ - Parses commands, prints human help, starts setup/server/tunnel flows, and
70
+ keeps compatibility commands behind focused help topics.
71
+ - Daily setup entrypoints are `computer-linker here` for the current folder
72
+ and `computer-linker start <workspace-path>` for explicit paths.
73
+ - Config and scope model: `src/config.ts`, `src/config-diagnostics.ts`,
74
+ `src/workspaces.ts`, `src/permissions.ts`, `src/capability-policy.ts`
75
+ - Own config load/write, machine identity, folder scopes, permission
76
+ presets, command policy defaults, and diagnostics.
77
+ - MCP and HTTP transport: `src/server.ts`, `src/mcp-surface.ts`,
78
+ `src/api.ts`, `src/oauth-provider.ts`, `src/http-auth.ts`
79
+ - Own protocol adapters, authentication, public MCP-only behavior, OAuth
80
+ metadata, and JSON API responses.
81
+ - Operation contract and dispatch: `src/computer-contract.ts`,
82
+ `src/computer-operation-registry.ts`, `src/workspace-operations.ts`
83
+ - Own the stable `computer_operation` envelope, operation metadata, aliases,
84
+ policy checks, and provider dispatch.
85
+ - Providers: `src/search.ts`, `src/processes.ts`, `src/codex-runs.ts`,
86
+ `src/screenshot.ts`, `src/platform-shell.ts`, `src/sensitive-files.ts`
87
+ - Own concrete local behavior for files/search, commands, managed processes,
88
+ Codex, screenshots, shell selection, and sensitive file blocking.
89
+ - Client helpers: `src/client.ts`, `src/client-smoke.ts`, `src/chatgpt.ts`
90
+ - Own reusable MCP client setup/smoke guidance. ChatGPT helpers are thin
91
+ compatibility exports over generic client guidance.
92
+ - Tunnels and public exposure: `src/tunnels.ts`
93
+ - Own provider detection, process start/status, public URL discovery, and
94
+ OpenAI tunnel-client installation/verification.
95
+ - Audit and release tooling: `src/audit.ts`, `scripts/*.mjs`
96
+ - Own operation history, public-release checks, package smoke, alpha
97
+ evidence, npm publish automation, and public mirror generation.
98
+
99
+ When adding a feature, first decide whether it is a CLI command, a protocol
100
+ contract change, a provider operation, a tunnel/exposure concern, or release
101
+ tooling. Keep new client-specific behavior thin and route it through the
102
+ generic MCP contract when possible.
103
+
104
+ `get_computer_info` is the public MCP introspection entrypoint. The local
105
+ `/api/v1/capabilities` endpoint and compatibility `get_capabilities` tool
106
+ expose the fuller implementation diagnostics for local tools, config, security,
66
107
  release readiness, and tunnel state. Together they expose OS/runtime facts,
67
108
  coding capability flags, local tool availability, executable paths, versions,
68
109
  install hints, workspace permissions, operation catalog, config diagnostics,
@@ -209,10 +250,11 @@ Workspace config can add an optional `policy` block per scope. Command,
209
250
  package, managed process, and Codex execution check `allowedCommands` and
210
251
  `deniedCommands` wildcard patterns before launch, cap runtime with
211
252
  `maxRuntimeSeconds`, and bound command stdout/stderr with `maxOutputBytes`.
212
- `computer-linker start <folder>` and `computer-linker setup <folder>` attach
213
- a default execution policy when `--shell` or `--codex` is enabled. Manual
214
- `workspace add/update` flows keep policy management explicit. Absent policy
215
- keeps the existing permission-flag behavior.
253
+ `computer-linker here`, `computer-linker start <folder>`, and
254
+ `computer-linker setup <folder>` attach a default execution policy when
255
+ `--shell` or `--codex` is enabled. Manual `workspace add/update` flows keep
256
+ policy management explicit. Absent policy keeps the existing permission-flag
257
+ behavior.
216
258
  Config diagnostics and security diagnostics warn when shell or Codex execution
217
259
  is enabled without an `allowedCommands` policy, because those operations remain
218
260
  cwd-bound local execution rather than a filesystem sandbox.
@@ -422,9 +464,9 @@ surface for the same config file used by the MCP server:
422
464
  local MCP/API URLs, security findings, tool availability, release readiness,
423
465
  and next actions.
424
466
  - `computer-linker doctor --fix` applies deterministic local config repairs.
425
- - `computer-linker setup` and `computer-linker start <folder>` initialize
426
- machine identity, owner token, workspace scopes, permissions, and default
427
- command policy.
467
+ - `computer-linker here`, `computer-linker setup`, and
468
+ `computer-linker start <folder>` initialize machine identity, owner token,
469
+ workspace scopes, permissions, and default command policy.
428
470
  - `computer-linker config ...` shows and edits config values such as
429
471
  `publicBaseUrl` and per-workspace execution policy.
430
472
  - `computer-linker process list/read/stop` talks to the running local HTTP
@@ -474,10 +516,11 @@ Computer Linker treats tunnel providers as local CLIs rather than hidden service
474
516
  Each provider implements `detect`, `status`, `expose`, `getPublicUrl`, and
475
517
  `stop`. The product-mode CLI entrypoint is `computer-linker start`, which starts
476
518
  local HTTP mode by default and starts a tunnel only when `--tunnel` is explicit.
477
- When a tunnel is selected, `computer-linker start --tunnel ...` and
478
- `computer-linker expose ...` enable `publicMcpOnly` before the HTTP server
479
- listens so public-host requests expose `/mcp` only; local `/api/v1` and
480
- `/healthz` remain available for CLI smoke checks.
519
+ When a tunnel is selected, `computer-linker here --tunnel ...`,
520
+ `computer-linker start --tunnel ...`, and `computer-linker expose ...` enable
521
+ `publicMcpOnly` before the HTTP server listens so public-host requests expose
522
+ `/mcp` only; local `/api/v1` and `/healthz` remain available for CLI smoke
523
+ checks.
481
524
  Tailscale product-mode startup uses Funnel by default once selected;
482
525
  `computer-linker expose <provider>` remains as a lower-level compatibility
483
526
  entrypoint:
@@ -509,10 +552,11 @@ such as Desktop for executables unless a path is explicitly provided with
509
552
  `computer-linker start` and `computer-linker expose` require an owner token
510
553
  before starting a tunnel. Loopback
511
554
  HTTP mode can run without a token for local-only development, and `init`,
512
- `setup`, `start <folder>`, or `config token rotate` can generate the token
513
- before exposure. Tunnel mode must not publish a loopback-only unauthenticated
514
- server to the network. The direct bearer owner-token compatibility path reads
515
- current config on each `/mcp` request, so token changes take effect immediately
555
+ `setup`, `here`, `start <folder>`, or `config token rotate` can generate the
556
+ token before exposure. Tunnel mode must not publish a loopback-only
557
+ unauthenticated server to the network. The direct bearer owner-token
558
+ compatibility path reads current config on each `/mcp` request, so token changes
559
+ take effect immediately
516
560
  for clients that send `Authorization: Bearer ...`. OAuth discovery and provider
517
561
  state are created when HTTP mode starts; restart the server after token-state
518
562
  changes for full OAuth client setup.
package/docs/chatgpt-setup.md CHANGED
@@ -6,8 +6,8 @@ ChatGPT workspace supports custom MCP apps / developer mode.
6
6
  ChatGPT cannot reach a server that only listens on `localhost` from your
7
7
  computer. For cloud-hosted ChatGPT clients, expose Computer Linker through an
8
8
  HTTPS URL. Cloudflare custom hostnames should be saved as `publicBaseUrl`
9
- before OAuth client setup; Tailscale Funnel URLs are detected and saved by
10
- `start C:\Projects\my-app --tunnel tailscale`.
9
+ before OAuth client setup; Tailscale Funnel URLs are detected and saved by
10
+ `here --tunnel tailscale` or `start C:\Projects\my-app --tunnel tailscale`.
11
11
 
12
12
  ## 1. Install
13
13
 
@@ -25,9 +25,12 @@ From this checkout, run `npm install` once and replace `computer-linker` with
25
25
  Pass the folder to `start`. Computer Linker creates the config, owner token,
26
26
  and workspace entry automatically before the server starts:
27
27
 
28
- ```powershell
29
- computer-linker start C:\Projects\my-app
30
- ```
28
+ ```powershell
29
+ cd C:\Projects\my-app
30
+ computer-linker here
31
+ ```
32
+
33
+ From another folder, use `computer-linker start C:\Projects\my-app`.
31
34
 
32
35
  If you want to configure without starting the server yet, use `setup`:
33
36
 
@@ -42,10 +45,10 @@ Permission meaning:
42
45
  - `shell`: run package scripts, commands, and managed shell processes
43
46
  - `codex`: invoke the local `codex` CLI in this workspace
44
47
 
45
- `start <folder>` and `setup <folder>` default to normal development access:
46
- file edits plus approved project commands. Use `--read-only` when ChatGPT
47
- should inspect without editing or running project commands. Add `--write`,
48
- `--shell`, or `--codex` separately only when you need finer control.
48
+ `here`, `start <folder>`, and `setup <folder>` default to normal development
49
+ access: file edits plus approved project commands. Use `--read-only` when
50
+ ChatGPT should inspect without editing or running project commands. Add
51
+ `--write`, `--shell`, or `--codex` separately only when you need finer control.
49
52
 
50
53
  When `start` or `setup` enables `--shell` or `--codex`, Computer Linker adds a
51
54
  default execution policy. The default policy allows common project commands
@@ -60,15 +63,17 @@ in the workspace but are not OS-level filesystem sandboxes.
60
63
 
61
64
  Cloudflare Quick Tunnel:
62
65
 
63
- ```powershell
64
- computer-linker start C:\Projects\my-app --tunnel cloudflare
65
- ```
66
+ ```powershell
67
+ cd C:\Projects\my-app
68
+ computer-linker here --tunnel cloudflare
69
+ ```
66
70
 
67
71
  Tailscale Funnel:
68
72
 
69
- ```powershell
70
- computer-linker start C:\Projects\my-app --tunnel tailscale
71
- ```
73
+ ```powershell
74
+ cd C:\Projects\my-app
75
+ computer-linker here --tunnel tailscale
76
+ ```
72
77
 
73
78
  You do not need to know `https://<machine>.<tailnet>.ts.net` before setup.
74
79
  Computer Linker detects that URL from `tailscale funnel` output or Tailscale
@@ -79,10 +84,11 @@ plain Tailscale DNS or Serve remains tailnet-only.
79
84
 
80
85
  OpenAI Secure MCP Tunnel:
81
86
 
82
- ```powershell
83
- $env:CONTROL_PLANE_API_KEY = "sk-..."
84
- computer-linker start C:\Projects\my-app --tunnel openai --tunnel-id tunnel_...
85
- ```
87
+ ```powershell
88
+ $env:CONTROL_PLANE_API_KEY = "sk-..."
89
+ cd C:\Projects\my-app
90
+ computer-linker here --tunnel openai --tunnel-id tunnel_...
91
+ ```
86
92
 
87
93
  This mode does not create a public MCP URL and does not need `publicBaseUrl`.
88
94
  In ChatGPT connector settings, choose **Tunnel** and select or paste the
package/docs/client-recipes.md CHANGED
@@ -5,11 +5,14 @@ connection details. Use `--show-token` only on a trusted local screen.
5
5
 
6
6
  ## Local MCP Clients
7
7
 
8
- Start Computer Linker:
9
-
10
- ```powershell
11
- computer-linker start C:\Projects\my-app
12
- ```
8
+ Start Computer Linker:
9
+
10
+ ```powershell
11
+ cd C:\Projects\my-app
12
+ computer-linker here
13
+ ```
14
+
15
+ From another folder, use `computer-linker start C:\Projects\my-app`.
13
16
 
14
17
  Configure the client:
15
18
 
@@ -28,10 +31,11 @@ computer-linker client smoke --allow-http --url http://127.0.0.1:3939/mcp
28
31
 
29
32
  Create the tunnel in OpenAI Platform, then start Computer Linker:
30
33
 
31
- ```powershell
32
- $env:CONTROL_PLANE_API_KEY = "sk-..."
33
- computer-linker start C:\Projects\my-app --tunnel openai --tunnel-id tunnel_...
34
- ```
34
+ ```powershell
35
+ $env:CONTROL_PLANE_API_KEY = "sk-..."
36
+ cd C:\Projects\my-app
37
+ computer-linker here --tunnel openai --tunnel-id tunnel_...
38
+ ```
35
39
 
36
40
  In the client, choose Tunnel mode and select or paste the `tunnel_...` id. Do
37
41
  not paste the Computer Linker bearer token into OpenAI Tunnel mode; the local
@@ -46,9 +50,10 @@ computer-linker history --view connections
46
50
 
47
51
  ## Tailscale Funnel
48
52
 
49
- ```powershell
50
- computer-linker start C:\Projects\my-app --tunnel tailscale
51
- ```
53
+ ```powershell
54
+ cd C:\Projects\my-app
55
+ computer-linker here --tunnel tailscale
56
+ ```
52
57
 
53
58
  Computer Linker detects the Funnel HTTPS origin and saves it as
54
59
  `publicBaseUrl`. Configure the client with the printed HTTPS URL plus `/mcp`
@@ -62,15 +67,17 @@ computer-linker client setup --show-token
62
67
 
63
68
  Quick tunnel:
64
69
 
65
- ```powershell
66
- computer-linker start C:\Projects\my-app --tunnel cloudflare
67
- ```
70
+ ```powershell
71
+ cd C:\Projects\my-app
72
+ computer-linker here --tunnel cloudflare
73
+ ```
68
74
 
69
75
  Owned hostname:
70
76
 
71
- ```powershell
72
- computer-linker start C:\Projects\my-app --url https://mcp.your-domain.com --tunnel cloudflare
73
- ```
77
+ ```powershell
78
+ cd C:\Projects\my-app
79
+ computer-linker here --url https://mcp.your-domain.com --tunnel cloudflare
80
+ ```
74
81
 
75
82
  Configure the client with `https://mcp.your-domain.com/mcp` and the bearer
76
83
  header from `computer-linker client setup --show-token`.
package/docs/getting-started.md ADDED
@@ -0,0 +1,187 @@
1
+ # Getting Started
2
+
3
+ This tutorial starts one local Computer Linker server, exposes one folder, and
4
+ connects an MCP client.
5
+
6
+ ## 1. Install
7
+
8
+ Computer Linker requires Node.js 20.12 or newer.
9
+
10
+ ```powershell
11
+ npm install -g @easonwumac/computer-linker
12
+ computer-linker check
13
+ ```
14
+
15
+ `check` uses a temporary config and temporary workspace. It is safe to run
16
+ before exposing real folders.
17
+
18
+ ## 2. Start In A Project Folder
19
+
20
+ Open a terminal in the folder you want the client to access:
21
+
22
+ ```powershell
23
+ cd C:\Projects\my-app
24
+ computer-linker here
25
+ ```
26
+
27
+ Leave that terminal running. The command creates config, owner token, workspace
28
+ entry, and a default coding policy if they do not already exist. The workspace
29
+ name defaults to the folder name.
30
+
31
+ From another folder, use the explicit path form:
32
+
33
+ ```powershell
34
+ computer-linker start C:\Projects\my-app
35
+ ```
36
+
37
+ Use read-only mode when the client should inspect without editing:
38
+
39
+ ```powershell
40
+ computer-linker here --read-only
41
+ ```
42
+
43
+ Use full trust only for folders where Codex operations and screen capture are
44
+ intended:
45
+
46
+ ```powershell
47
+ computer-linker here --full-trust
48
+ ```
49
+
50
+ ## 3. Configure A Local MCP Client
51
+
52
+ In a second terminal:
53
+
54
+ ```powershell
55
+ computer-linker client setup
56
+ ```
57
+
58
+ For local clients that need the bearer token, show it only on a trusted local
59
+ screen:
60
+
61
+ ```powershell
62
+ computer-linker client setup --show-token
63
+ ```
64
+
65
+ Typical local settings:
66
+
67
+ - URL: `http://127.0.0.1:3939/mcp`
68
+ - Auth header: `Authorization: Bearer <ownerToken>`
69
+ - Agent instructions: [agent-instructions.md](agent-instructions.md)
70
+
71
+ Verify the client path:
72
+
73
+ ```powershell
74
+ computer-linker diagnose client --local
75
+ ```
76
+
77
+ ## 4. Expose To A Cloud MCP Client
78
+
79
+ Cloud MCP clients cannot reach `127.0.0.1`. Start with a tunnel only when you
80
+ need cloud access.
81
+
82
+ OpenAI Secure MCP Tunnel:
83
+
84
+ ```powershell
85
+ $env:CONTROL_PLANE_API_KEY = "sk-..."
86
+ cd C:\Projects\my-app
87
+ computer-linker here --tunnel openai --tunnel-id tunnel_...
88
+ ```
89
+
90
+ This mode does not create a public URL. In the client, choose Tunnel mode and
91
+ select or paste the `tunnel_...` id. Do not paste the Computer Linker bearer
92
+ token into OpenAI Tunnel mode; the local tunnel client forwards it to the
93
+ loopback MCP server.
94
+
95
+ Tailscale Funnel:
96
+
97
+ ```powershell
98
+ cd C:\Projects\my-app
99
+ computer-linker here --tunnel tailscale
100
+ ```
101
+
102
+ Computer Linker detects the Funnel HTTPS origin, saves it as `publicBaseUrl`,
103
+ and prints the MCP URL.
104
+
105
+ Cloudflare quick tunnel:
106
+
107
+ ```powershell
108
+ cd C:\Projects\my-app
109
+ computer-linker here --tunnel cloudflare
110
+ ```
111
+
112
+ Cloudflare hostname you own:
113
+
114
+ ```powershell
115
+ cd C:\Projects\my-app
116
+ computer-linker here --url https://mcp.your-domain.com --tunnel cloudflare
117
+ ```
118
+
119
+ After starting a public tunnel, inspect the exposed state:
120
+
121
+ ```powershell
122
+ computer-linker tunnel status
123
+ computer-linker history --view connections
124
+ computer-linker client setup
125
+ ```
126
+
127
+ Public tunnel mode exposes only `/mcp` to public-host requests. Local `/api`
128
+ and `/healthz` remain available for local diagnostics.
129
+
130
+ ## 5. What Agents Should Call
131
+
132
+ The main MCP tools are:
133
+
134
+ - `get_computer_info`: inspect computer identity, scopes, policy, URLs, and
135
+ available operations.
136
+ - `computer_operation`: run one operation using the generic envelope
137
+ `{ "scope": "...", "op": "...", "target": "...", "input": {}, "options": {} }`.
138
+ - `get_operation_history`: inspect redacted recent activity.
139
+
140
+ Use [agent-instructions.md](agent-instructions.md) as the client prompt. It
141
+ keeps agents on the generic `computer_operation` contract instead of older
142
+ compatibility tools.
143
+
144
+ ## 6. Daily Commands
145
+
146
+ ```powershell
147
+ computer-linker status
148
+ computer-linker status --details
149
+ computer-linker workspace list
150
+ computer-linker history --view last
151
+ computer-linker config token
152
+ computer-linker help advanced
153
+ ```
154
+
155
+ `status` is the short human check. Use `--details` only when investigating a
156
+ warning.
157
+
158
+ ## Troubleshooting
159
+
160
+ If a client cannot connect:
161
+
162
+ ```powershell
163
+ computer-linker diagnose client
164
+ computer-linker tunnel status
165
+ computer-linker history --view connections
166
+ ```
167
+
168
+ If the terminal shows an OpenAI tunnel organization 401, verify the API key's
169
+ Platform organization, Tunnels Read + Use permission, and client workspace
170
+ association before changing Computer Linker config.
171
+
172
+ If a command is denied, inspect the workspace policy:
173
+
174
+ ```powershell
175
+ computer-linker workspace list
176
+ computer-linker config policy <workspace-id> --json
177
+ ```
178
+
179
+ If you need the low-level server mode, use:
180
+
181
+ ```powershell
182
+ computer-linker help advanced
183
+ computer-linker serve --transport http
184
+ ```
185
+
186
+ For normal use, prefer `computer-linker here` or
187
+ `computer-linker start <workspace-path>`.
package/docs/manual-test-plan.md CHANGED
@@ -4,8 +4,11 @@ Use this plan before sharing an alpha build or when dogfooding a local
4
4
  checkout. It keeps the first test isolated from your real Computer Linker
5
5
  config.
6
6
 
7
- Commands below assume this checkout and use `npm run dev --`. When testing an
8
- installed package instead, replace `npm run dev --` with `computer-linker`.
7
+ Commands below assume this checkout and use `npm run dev --`. Because that
8
+ runner executes from the source checkout, use `start <path>` when the target
9
+ folder is elsewhere. When testing an installed package instead, replace
10
+ `npm run dev --` with `computer-linker`; installed-package checks can also run
11
+ `computer-linker here` from inside the target folder.
9
12
 
10
13
  ## 1. Build Gate
11
14
 
@@ -64,8 +67,8 @@ Expected:
64
67
 
65
68
  - `config validate` does not report `blocked`
66
69
  - `workspace list` shows the `app` scope named from the checkout folder
67
- - first-run `setup` / `start <folder>` does not leave the bootstrap `current`
68
- scope in the config
70
+ - first-run `here`, `setup`, or `start <folder>` does not leave the bootstrap
71
+ `current` scope in the config
69
72
  - `status` says `doctor --fix` removes the bootstrap `current` scope instead
70
73
  of implying it will only add an execution policy
71
74
  - new workspaces are read-only unless you explicitly add `--write`
@@ -80,11 +83,19 @@ Expected:
80
83
  connection summary, and the next start/client setup commands. Full WAF and
81
84
  policy details stay in `setup --json`.
82
85
 
83
- Tailscale Funnel variant:
84
-
85
- ```powershell
86
- npm run dev -- start C:\Projects\my-app --tunnel tailscale
87
- ```
86
+ Tailscale Funnel variant:
87
+
88
+ ```powershell
89
+ npm run dev -- start C:\Projects\my-app --tunnel tailscale
90
+ ```
91
+
92
+ Installed-package `here` variant:
93
+
94
+ ```powershell
95
+ Push-Location C:\Projects\my-app
96
+ computer-linker here --tunnel tailscale
97
+ Pop-Location
98
+ ```
88
99
 
89
100
  Expected:
90
101
 
@@ -99,10 +110,19 @@ Expected:
99
110
 
100
111
  OpenAI Secure MCP Tunnel variant:
101
112
 
102
- ```powershell
103
- $env:CONTROL_PLANE_API_KEY = "sk-..."
104
- npm run dev -- start C:\Projects\my-app --tunnel openai --tunnel-id tunnel_...
105
- ```
113
+ ```powershell
114
+ $env:CONTROL_PLANE_API_KEY = "sk-..."
115
+ npm run dev -- start C:\Projects\my-app --tunnel openai --tunnel-id tunnel_...
116
+ ```
117
+
118
+ Installed-package `here` variant:
119
+
120
+ ```powershell
121
+ $env:CONTROL_PLANE_API_KEY = "sk-..."
122
+ Push-Location C:\Projects\my-app
123
+ computer-linker here --tunnel openai --tunnel-id tunnel_...
124
+ Pop-Location
125
+ ```
106
126
 
107
127
  Expected:
108
128
 
@@ -240,18 +260,21 @@ npm run dev -- client chatgpt verify --mode coding
240
260
  npm run dev -- start
241
261
  ```
242
262
 
243
- Or:
244
-
245
- ```powershell
246
- npm run dev -- start C:\Projects\my-app --tunnel tailscale
247
- ```
248
-
249
- Or:
250
-
251
- ```powershell
252
- $env:CONTROL_PLANE_API_KEY = "sk-..."
253
- npm run dev -- start C:\Projects\my-app --tunnel openai --tunnel-id tunnel_...
254
- ```
263
+ Or:
264
+
265
+ ```powershell
266
+ npm run dev -- start C:\Projects\my-app --tunnel tailscale
267
+ ```
268
+
269
+ Or:
270
+
271
+ ```powershell
272
+ $env:CONTROL_PLANE_API_KEY = "sk-..."
273
+ npm run dev -- start C:\Projects\my-app --tunnel openai --tunnel-id tunnel_...
274
+ ```
275
+
276
+ When testing the installed package instead of the source checkout, run
277
+ `computer-linker here --tunnel ...` from inside `C:\Projects\my-app`.
255
278
 
256
279
  Expected:
257
280
 
package/docs/product-spec.md CHANGED
@@ -803,10 +803,11 @@ The human management surface is CLI-first:
803
803
  The product should not rely on a local browser dashboard for setup or
804
804
  operations. The JSON API remains a protocol surface for MCP clients,
805
805
  automation, and smoke checks rather than a human-facing management UI.
806
- The default CLI help should stay short and focused on first-run start, tunnel
807
- selection, client setup, status, and quickstart preview. Self-test, smoke,
808
- repair, service/config/API, history, and compatibility commands remain available
809
- through advanced or focused help topics rather than the first-run surface.
806
+ The default CLI help should stay short and focused on first-run `here`,
807
+ explicit-path start, tunnel selection, client setup, status, and quickstart
808
+ preview. Self-test, smoke, repair, service/config/API, history, and
809
+ compatibility commands remain available through advanced or focused help topics
810
+ rather than the first-run surface.
810
811
 
811
812
  Required management actions:
812
813
 
package/docs/release-checklist.md CHANGED
@@ -30,17 +30,15 @@ npm run public:check
30
30
 
31
31
  ## Local npm Release Automation
32
32
 
33
- Use the local wrapper when you are ready to publish from the current repository:
34
-
35
- ```bash
36
- npm run release:check
37
- npm run release:dry-run
38
- npm run release:publish -- --create-tag --push --otp <code>
33
+ Use the local wrapper when you are ready to publish from the current repository:
34
+
35
+ ```bash
36
+ npm run release -- --otp <code>
39
37
  ```
40
-
41
- `release:check` runs the local product and public package gates without
42
- publishing. It does not require a clean worktree, so it is useful before the
43
- final release commit.
38
+
39
+ `release:check` runs the local product and public package gates without
40
+ publishing. It does not require a clean worktree, so it is useful before the
41
+ final release commit.
44
42
 
45
43
  `release:dry-run` requires the release commit to be clean and on main/master.
46
44
  It runs `npm publish --dry-run`; if `v<package.version>` is missing, it creates
@@ -56,6 +54,10 @@ release tag automatically before publishing, `--otp <code>` for npm 2FA, and
56
54
  version metadata, verifies the configured npm dist-tag, and runs the published
57
55
  CLI from a clean temporary directory. `release:verify` repeats only that
58
56
  post-publish registry check for the current `package.json` version.
57
+ `release` is the productized one-command path for normal local publishing; it
58
+ uses the lower-level `release:publish` behavior with automatic tag creation and
59
+ push enabled. Use `npm run release:publish -- --create-tag --push --otp <code>`
60
+ only when debugging that lower-level publish wrapper directly.
59
61
  On Windows, a `NODE_AUTH_TOKEN` saved in the User environment is loaded into
60
62
  the release process automatically when the current shell has not inherited it.
61
63
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@easonwumac/computer-linker",
3
- "version": "0.1.8",
3
+ "version": "0.1.10",
4
4
  "description": "One computer, one permissioned MCP linker for local workspaces.",
5
5
  "type": "module",
6
6
  "main": "dist/client.js",
@@ -61,6 +61,7 @@
61
61
  "public:release-ready": "node scripts/alpha-readiness-report.mjs --accept-public-snapshot --require-evidence --require-dated-changelog",
62
62
  "public:repo-ready": "npm run product:check && npm run public:audit -- --strict-history",
63
63
  "public:snapshot": "node scripts/create-public-snapshot.mjs",
64
+ "release": "node scripts/release-npm.mjs --publish --create-tag --push",
64
65
  "release:check": "node scripts/release-npm.mjs --check",
65
66
  "release:dry-run": "node scripts/release-npm.mjs --dry-run",
66
67
  "release:publish": "node scripts/release-npm.mjs --publish",