docs(ports): document public service ports

.opencode/opencode.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "computercraft-mcp-bridge": {
+      "type": "remote",
+      "url": "http://127.0.0.1:3000",
+      "enabled": true
+    }
+  }
+}

.plans/mcp-computer-lua-plan.md

@@ -17,20 +17,22 @@ pong from <computerId> (Label: <computerLabel>)
 - Lua program path: `programs/mcp-computer.lua`.
 - Package: `trapos-sandbox`.
 - The program connects outbound to the bridge's ComputerCraft link port.
-- The implemented bridge link default is `ws://<host>:3001` (`CC_LINK_PORT`, default `3001`).
+- The implemented local/dev bridge link default is `ws://<host>:3001` (`CC_LINK_PORT`, default `3001`). Production/public bridge deployments use `ws://<host>:4243` with `CC_LINK_PORT=4243`; see [`../docs/public-ports.md`](../docs/public-ports.md).
 - The host-side MCP tool is named `probe-computers` and broadcasts to every connected computer.
 - No link auth for the first version.
 - Keep the first Lua implementation as a program, not an autostart server, until the bridge loop is proven.
-- The implemented bridge accepts WebSocket connections on any path, so a bare `ws://<host>:3001` URL is sufficient.
+- The implemented bridge accepts WebSocket connections on any path, so a bare local/dev URL such as `ws://<host>:3001` is sufficient.
 
 ## Background
 
 CC:Tweaked cannot listen on real HTTP/TCP ports with standard APIs. It can connect outward using `http.websocket`. This program is therefore the in-game half of the bridge:
 
 ```text
-[ CC computer ] --outbound WebSocket--> [ tools/mcp-bridge link listener :3001 ]
+[ CC computer ] --outbound WebSocket--> [ tools/mcp-bridge link listener :3001 local/dev, :4243 production ]
 ```
 
+Production deployments use the public ComputerCraft bridge WebSocket port `4243` instead of the local/dev default `3001`.
+
 The Lua program is effectively an agent. It identifies itself to the bridge, waits for JSON request frames, executes supported methods, and sends JSON response frames. The host bridge is already implemented and exposes MCP over plain HTTP JSON-RPC on `MCP_PORT` while this Lua program only speaks the ComputerCraft WebSocket link protocol.
 
 ## User Interface
@@ -49,6 +51,7 @@ Examples:
 ```text
 mcp-computer ws://192.168.1.20:3001
 mcp-computer -url ws://mcp-bridge.local:3001
+mcp-computer ws://public.example.com:4243
 ```
 
 The program should print clear status lines:
@@ -220,7 +223,7 @@ After editing Lua or package descriptors:
 ## Manual Validation
 
 1. Start the TypeScript bridge.
-2. On one ComputerCraft computer, run `mcp-computer ws://<bridge-host>:3001`.
+2. On one ComputerCraft computer, run `mcp-computer ws://<bridge-host>:3001` for local/dev, or `mcp-computer ws://<public-host>:4243` for public production.
 3. Confirm the bridge logs the computer registration.
 4. Connect an MCP client to the bridge MCP port.
 5. Call `probe-computers`.

docs/README.md

@@ -10,6 +10,7 @@ Start here when looking up ComputerCraft-related APIs, CraftOS-PC behavior, peri
 - [`create_cc_tweaked_glossary.md`](create_cc_tweaked_glossary.md) - Create CC:Tweaked integration pages.
 - [`opencode_server_guide.md`](opencode_server_guide.md) - Running `opencode serve` for the TrapOS `ai` client.
 - [`opencode_api.md`](opencode_api.md) - Minimal opencode HTTP API reference used by TrapOS.
+- [`public-ports.md`](public-ports.md) - Public production TCP port allocation for TrapOS services.
 - [`adrs/`](adrs/) - Lightweight Architecture Decision Records for this repository.
 
 ## Notes

docs/adrs/adr-0016-js-tool-verification.md

@@ -23,6 +23,7 @@ Keep the Node package scripts simple and one-purpose:
 - `npm run check` runs ESLint. TypeScript compilation is covered by `npm run build` and `npm run test:ci` to avoid duplicate compiler runs in repository CI.
 - `npm run test:ci` runs `npm run check && npm run build && npm run test`, so type errors and lint failures both surface even though `test` itself no longer compiles.
 - `npm run test-integration` runs the bridge-to-CraftOS integration suite with `tsx --test --test-concurrency=1 test-integration/*.test.ts`. Each case boots the bridge in-process on fixed loopback ports (`127.0.0.1:2000` for MCP HTTP, `127.0.0.1:2001` for the CraftOS link), spawns a CraftOS-PC headless computer that connects back, exercises `tools/call probe-computers`, and tears everything down. `--test-concurrency=1` keeps the fixed ports collision-free.
+- These fixed integration-test ports are loopback-only and unrelated to the public production ports documented in [`../public-ports.md`](../public-ports.md).
 
 Expose matching repository recipes for the Node lifecycle:
 

docs/opencode_api.md

@@ -4,12 +4,22 @@ Minimal reference for the endpoints used by `libai.lua`. Full spec served at `GE
 
 ## Running the server
 
+Local/dev uses opencode's default port `4096`:
+
 ```bash
 opencode serve \
   --hostname 127.0.0.1 \
   --port 4096
 ```
 
+Public production uses port `4242`; see [`public-ports.md`](public-ports.md):
+
+```bash
+opencode serve \
+  --hostname 0.0.0.0 \
+  --port 4242
+```
+
 With Basic Auth (recommended):
 
 ```bash

docs/opencode_server_guide.md

@@ -24,10 +24,18 @@ ccpm install trapos
 
 ## 1. Start `opencode serve`
 
+Local/dev uses opencode's default port `4096`:
+
 ```bash
 opencode serve --hostname 0.0.0.0 --port 4096
 ```
 
+Public production uses port `4242`; see [`public-ports.md`](public-ports.md):
+
+```bash
+opencode serve --hostname 0.0.0.0 --port 4242
+```
+
 With Basic Auth (recommended for LAN exposure):
 
 ```bash
@@ -72,6 +80,12 @@ Use the CraftOS shell `set` program at the ComputerCraft console or CraftOS-PC t
 set opencc.server_url http://<host-ip>:4096
 ```
 
+For public production, use port `4242`:
+
+```sh
+set opencc.server_url http://<public-host>:4242
+```
+
 For example locally:
 
 ```sh
@@ -108,7 +122,8 @@ set opencc.poll_interval_seconds 2
 `opencc.session_id` is auto-managed and saved by `ai`. Set it manually only when you want CC to target an existing session, such as one opened in the attached TUI.
 
 - **CraftOS-PC (localhost):** `http://127.0.0.1:4096`
-- **In-game ATM10:** use your LAN IP (e.g. `192.168.x.x`) — add it to `http.rules` in `config/computercraft-server.toml`
+- **In-game ATM10 local/dev:** use your LAN IP with port `4096` (e.g. `192.168.x.x:4096`) — add it to `http.rules` in `config/computercraft-server.toml`
+- **Public production:** use your public host with port `4242`
 
 ## 4. Run `ai`
 

docs/public-ports.md

@@ -0,0 +1,18 @@
+# Public Production Ports
+
+TrapOS public production services use the `4242-4244` TCP range. Keep local developer defaults separate from these public ports so tests and local tools can run without binding production-facing addresses.
+
+| Port | Service | Notes |
+|---|---|---|
+| `4242` | opencode server HTTP API | Production/public port for `opencode serve`. Local/dev examples may still use opencode's default `4096`. |
+| `4243` | ComputerCraft bridge WebSocket | Production/public equivalent of the local bridge link default `3001`. Use `CC_LINK_PORT=4243` for production bridge deployments. |
+| `4244` | Reserved | Free public production port reserved for a future service. Do not assign it casually in local tooling. |
+
+## Local Vs Production
+
+- Local/dev opencode: `http://127.0.0.1:4096`.
+- Public/production opencode: `http://<public-host>:4242`.
+- Local/dev ComputerCraft bridge link: `ws://<host>:3001`.
+- Public/production ComputerCraft bridge link: `ws://<public-host>:4243`.
+
+Production services exposed on public ports should use the normal deployment controls for the host: authentication where supported, firewall rules, and TLS or a reverse proxy when crossing untrusted networks.