relmio 0.2.0

package/docs/maintenance.md

@@ -0,0 +1,157 @@
+# Refresh, upgrade, rollback, and uninstall
+
+Every command on this page targets the separate
+`n8n-openai-oauth` project. None targets the n8n project.
+
+## Refresh an expired ChatGPT login
+
+The easiest method:
+
+1. Start the local wizard again.
+2. Select **Refresh ChatGPT sign-in**.
+3. Complete the newest browser sign-in page.
+4. Confirm that the **Credential updated** time matches the fresh sign-in.
+5. Connect to the same VPS and select the same n8n network.
+6. Approve the sidecar plan.
+
+The wizard replaces the sidecar credential and starts only the sidecar service.
+n8n is not restarted. Its local credential is stored separately at
+`~/.n8n-openai-oauth/auth.json`.
+
+Manual POSIX-shell method:
+
+```bash
+install -d -m 0700 "$HOME/.n8n-openai-oauth"
+npx --yes --ignore-scripts openai-oauth@2.0.0 login \
+  --open \
+  --login-timeout-ms 300000 \
+  --oauth-file "$HOME/.n8n-openai-oauth/auth.json"
+scp "$HOME/.n8n-openai-oauth/auth.json" \
+  root@YOUR_VPS_IP:/docker/n8n-openai-oauth/auth/auth.json
+```
+
+Then on the VPS:
+
+```bash
+chown 1000:1000 /docker/n8n-openai-oauth/auth/auth.json
+chmod 600 /docker/n8n-openai-oauth/auth/auth.json
+docker compose \
+  --project-name n8n-openai-oauth \
+  --file /docker/n8n-openai-oauth/docker-compose.yml \
+  up -d --wait --wait-timeout 60 --no-deps openai-oauth
+```
+
+## Restart only the sidecar
+
+```bash
+docker compose \
+  --project-name n8n-openai-oauth \
+  --file /docker/n8n-openai-oauth/docker-compose.yml \
+  restart openai-oauth
+```
+
+This does not restart n8n.
+
+## Safe source-code update
+
+On the local computer:
+
+```bash
+git pull --ff-only
+npm ci --ignore-scripts
+npm test
+npm start
+```
+
+Review release notes and the generated plan before approving another VPS
+installation.
+
+## Optional maintainer architecture map
+
+Graphify is useful for long-term maintenance because it exposes the boundaries
+between the local wizard, OAuth credential flow, SSH verification, sidecar
+deployment, and n8n recipes. It is an optional maintainer tool, not a runtime
+dependency:
+
+```bash
+graphify .
+```
+
+Keep the generated `graphify-out/` directory local. It is intentionally ignored
+by Git and excluded from the npm package because raw graphs can reveal internal
+file relationships, local paths, and unfinished implementation details. Put
+only reviewed, redacted diagrams or plain-language architecture notes in the
+public repository. Never include credentials, setup URLs, VPS addresses, or
+private screenshots in a graph export.
+
+## Updating the pinned bridge version
+
+Do not change `openai-oauth@2.0.0` casually. An upgrade requires:
+
+1. Read the upstream changelog and legal notes.
+2. Inspect the package tarball and install scripts.
+3. Update both the local login command and generated Dockerfile pin.
+4. Run all tests and the fake-data browser flow.
+5. Build the sidecar on a disposable VPS first.
+6. Verify `/health`, `/v1/models`, `/v1/responses`, streaming, and tool calls.
+7. Verify `docker compose port openai-oauth 10531` still returns no mapping.
+8. Confirm n8n was not restarted.
+
+Keep the old Docker image until the new one passes.
+
+## If n8n is upgraded
+
+This project does not alter the n8n image. A normal n8n image update can still
+change node behavior or Docker networks.
+
+After an n8n upgrade:
+
+1. Confirm n8n is healthy.
+2. Confirm its network name still matches the sidecar network.
+3. Retry the OpenAI credential.
+4. Verify one simple OpenAI Chat Model prompt.
+
+If the network name changed, rerun the wizard and select the new shared
+network. Do not edit or rebuild n8n merely to repair the sidecar.
+
+## Roll back or disable the bridge
+
+Stop and remove only the sidecar container:
+
+```bash
+docker compose \
+  --project-name n8n-openai-oauth \
+  --file /docker/n8n-openai-oauth/docker-compose.yml \
+  down
+```
+
+The files and OAuth credential remain available for recovery. n8n remains
+running.
+
+In n8n, disable workflows that depend on the bridge or replace their OpenAI
+credential.
+
+## Recoverable uninstall
+
+First run the sidecar-only `down` command above. Then move the project directory
+to a dated backup:
+
+```bash
+mv /docker/n8n-openai-oauth \
+  "/docker/n8n-openai-oauth.disabled-$(date +%Y%m%d-%H%M%S)"
+```
+
+This is recoverable: move the directory back if needed. After confirming the
+backup is no longer required, remove it through your normal VPS backup and
+retention process.
+
+Finally, delete the unused n8n credential through the n8n interface. Never
+delete or recreate the n8n container as part of this uninstall.
+
+## Future official n8n support
+
+As of July 28, 2026, an
+[open n8n pull request](https://github.com/n8n-io/n8n/pull/29184) proposes
+native OpenAI Account authentication for the OpenAI Chat Model. It is not yet
+merged. If n8n later ships and documents an official equivalent, prefer the
+official built-in route and retire this sidecar after testing migration.

package/docs/manual-install.md

@@ -0,0 +1,282 @@
+# Beginner manual installation
+
+Use this guide if the browser wizard cannot be used, or if you need to
+reproduce, debug, or improve the underlying installation method. The wizard is
+safer for routine installation because it validates names, confirms the host
+fingerprint, uploads files with SFTP, and limits the commands it can run.
+
+This guide never changes the existing n8n Compose file or image. It creates a
+second Compose project.
+
+## Before starting
+
+The commands in this fallback use a POSIX shell. You need:
+
+- a local macOS or Linux computer with Node.js 22 or newer, or Windows with
+  WSL/Git Bash and Node.js 22 or newer;
+- your VPS IP address;
+- the VPS root password;
+- the name of the running n8n container;
+- an existing Docker network shared by n8n and the reverse proxy, commonly
+named `proxy`.
+
+Before connecting to the VPS, export or otherwise back up every n8n workflow.
+The commands below are intentionally limited to the separate
+`n8n-openai-oauth` project and contain no n8n deletion, restart, or rebuild
+command, but they still authenticate to your VPS and write files. Keep a
+recoverable backup before proceeding.
+
+Replace every example such as `YOUR_VPS_IP` and `n8n-n8n-1` with the value
+shown on your own VPS. Never type the asterisks used to hide an IP in a
+screenshot.
+
+## Part 1: sign in on your own computer
+
+Open Terminal on your computer, not the Hostinger web terminal:
+
+```bash
+install -d -m 0700 "$HOME/.n8n-openai-oauth"
+npx --yes --ignore-scripts openai-oauth@2.0.0 login \
+  --open \
+  --login-timeout-ms 300000 \
+  --oauth-file "$HOME/.n8n-openai-oauth/auth.json"
+```
+
+Complete the newly opened sign-in page within five minutes. An old sign-in tab
+can expire; always use the page opened by the newest command.
+
+Confirm that the local file exists:
+
+```bash
+test -s "$HOME/.n8n-openai-oauth/auth.json" \
+  && echo "OAuth file is ready"
+```
+
+This dedicated path avoids reusing or overwriting the Codex app credential at
+`~/.codex/auth.json`. Do not print either file or paste its contents into
+chat.
+
+## Part 2: inspect n8n on the VPS
+
+Connect from your computer:
+
+```bash
+ssh root@YOUR_VPS_IP
+```
+
+The first connection asks whether you trust the SSH fingerprint. Compare the
+address carefully, type `yes`, and press Return. When SSH asks for a password,
+nothing appears while you type; that is normal.
+
+List the running containers:
+
+```bash
+docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Ports}}'
+```
+
+Find the row whose image is `docker.n8n.io/n8nio/n8n`. Copy its container name,
+then inspect its networks:
+
+```bash
+docker inspect n8n-n8n-1 --format '{{range $name, $_ := .NetworkSettings.Networks}}{{println $name}}{{end}}'
+```
+
+An output such as `proxy` is not “nothing”; it is the network name.
+
+## Part 3: create the separate sidecar project
+
+Still in the VPS terminal:
+
+```bash
+install -d -m 0755 /docker/n8n-openai-oauth
+install -d -m 0700 -o 1000 -g 1000 /docker/n8n-openai-oauth/auth
+```
+
+Create `/docker/n8n-openai-oauth/Dockerfile` with exactly:
+
+```dockerfile
+FROM node:22-bookworm-slim
+
+RUN npm install --global --ignore-scripts openai-oauth@2.0.0 \
+    && npm cache clean --force
+
+USER node
+
+ENTRYPOINT ["openai-oauth"]
+CMD ["--host", "0.0.0.0", "--port", "10531", "--oauth-file", "/home/node/.codex/auth.json"]
+```
+
+The `CMD` must stay on one line. If the JSON array is split incorrectly,
+Docker reports `unknown instruction: "--host"`.
+
+Create `/docker/n8n-openai-oauth/docker-compose.yml` with exactly the following.
+If your network is not named `proxy`, change only the final `name: proxy` line.
+
+```yaml
+services:
+  openai-oauth:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    restart: unless-stopped
+    init: true
+    volumes:
+      - ./auth:/home/node/.codex
+    expose:
+      - "10531"
+    networks:
+      n8n-shared:
+        aliases:
+          - n8n-openai-oauth
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    read_only: true
+    tmpfs:
+      - /tmp:size=16m,mode=1777
+      - /home/node/.local:uid=1000,gid=1000,mode=0700
+    pids_limit: 128
+    mem_limit: 512m
+    cpus: 1.0
+    healthcheck:
+      test:
+        - CMD
+        - node
+        - -e
+        - 'fetch("http://127.0.0.1:10531/health").then((response) => process.exit(response.ok ? 0 : 1)).catch(() => process.exit(1))'
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 20s
+    labels:
+      io.n8n-openai-oauth.managed: "true"
+
+networks:
+  n8n-shared:
+    external: true
+    name: proxy
+```
+
+There is deliberately no `ports:` section and no Traefik label.
+
+## Part 4: copy the OAuth file
+
+Leave the SSH session:
+
+```bash
+exit
+```
+
+Back in the Terminal on your own computer:
+
+```bash
+scp "$HOME/.n8n-openai-oauth/auth.json" \
+  root@YOUR_VPS_IP:/docker/n8n-openai-oauth/auth/auth.json
+```
+
+Do not include `**` around the IP. In zsh, asterisks are wildcard characters
+and cause `no matches found`.
+
+Return to the VPS:
+
+```bash
+ssh root@YOUR_VPS_IP
+chown 1000:1000 /docker/n8n-openai-oauth/auth/auth.json
+chmod 600 /docker/n8n-openai-oauth/auth/auth.json
+```
+
+Run `chown` on the VPS, not on your computer.
+
+## Part 5: validate and start only the sidecar
+
+Use the explicit project name and file on every command:
+
+```bash
+docker compose \
+  --project-name n8n-openai-oauth \
+  --file /docker/n8n-openai-oauth/docker-compose.yml \
+  config --quiet
+```
+
+Build only `openai-oauth`:
+
+```bash
+docker compose \
+  --project-name n8n-openai-oauth \
+  --file /docker/n8n-openai-oauth/docker-compose.yml \
+  build openai-oauth
+```
+
+Start only `openai-oauth`, with no dependencies:
+
+```bash
+docker compose \
+  --project-name n8n-openai-oauth \
+  --file /docker/n8n-openai-oauth/docker-compose.yml \
+  up -d --wait --wait-timeout 60 --no-deps openai-oauth
+```
+
+None of these commands reference the n8n Compose file or service.
+
+## Part 6: verify
+
+Check the final logs:
+
+```bash
+docker compose \
+  --project-name n8n-openai-oauth \
+  --file /docker/n8n-openai-oauth/docker-compose.yml \
+  logs --tail=50 openai-oauth
+```
+
+The successful lines include:
+
+```text
+OpenAI-compatible endpoint ready at http://0.0.0.0:10531/v1
+Available Models: ...
+```
+
+The warning about `--host 0.0.0.0` is expected inside the container. The
+Compose file does not publish the port to the VPS.
+
+Prove that no host port is published:
+
+```bash
+docker compose \
+  --project-name n8n-openai-oauth \
+  --file /docker/n8n-openai-oauth/docker-compose.yml \
+  port openai-oauth 10531
+```
+
+Success is no output.
+
+Check the models from inside the sidecar:
+
+```bash
+docker compose \
+  --project-name n8n-openai-oauth \
+  --file /docker/n8n-openai-oauth/docker-compose.yml \
+  exec -T openai-oauth \
+  node -e 'fetch("http://127.0.0.1:10531/v1/models").then(async (response) => { console.log(await response.text()); process.exit(response.ok ? 0 : 1); }).catch(() => process.exit(1))'
+```
+
+## Part 7: configure n8n
+
+In the n8n OpenAI credential:
+
+```text
+API Key: local-only
+Organization ID: leave empty
+Base URL: http://n8n-openai-oauth:10531/v1
+Add Custom Header: off
+```
+
+Do not use `http://127.0.0.1:10531/v1` in n8n. Inside the n8n container,
+`127.0.0.1` means n8n itself. The private Docker hostname is
+`n8n-openai-oauth`.
+
+In OpenAI Chat Model node version 1.3, keep **Use Responses API** on. If the
+switch is absent, keep the earlier node version's default Chat Completions
+behavior. Choose a model from the verified list and test a simple prompt before
+adding tools.

package/docs/n8n-configuration.md

@@ -0,0 +1,199 @@
+# Configure n8n nodes
+
+Use this page after the wizard reaches **The private bridge is ready**. Each
+value is in its own code block so it can be copied separately.
+
+## 1. Create the OpenAI credential
+
+In n8n, create or edit an **OpenAI** credential.
+
+### API Key
+
+```text
+local-only
+```
+
+This is a required n8n placeholder, not an OpenAI Platform API key or secret.
+
+### Base URL
+
+```text
+http://n8n-openai-oauth:10531/v1
+```
+
+### Organization ID
+
+Leave this field empty.
+
+### Add Custom Header
+
+```text
+Off
+```
+
+Save and test the credential. If n8n cannot reach it, confirm that n8n and the
+sidecar share a Docker network and that the Base URL uses the private
+`n8n-openai-oauth` hostname rather than `127.0.0.1`.
+
+## 2. OpenAI Chat Model for an AI Agent or Basic LLM Chain
+
+Use the same **OpenAI Chat Model** sub-node for either parent node.
+
+1. Add an **AI Agent** or **Basic LLM Chain** node.
+2. Add an **OpenAI Chat Model** to its **Chat Model** or **Model** connector.
+3. Select the OpenAI credential created above.
+4. In **Model**, select one of the model IDs detected by the wizard.
+5. On OpenAI Chat Model node version 1.3, turn **Use Responses API** on.
+6. Begin with no built-in tools and a simple test prompt.
+
+If **Use Responses API** is absent, the workflow is using an earlier Chat
+Model node version. Keep its default Chat Completions behavior; the bridge also
+supports:
+
+```text
+/v1/chat/completions
+```
+
+Do not copy a model name from the README screenshot. Paste or select one from
+the current wizard result:
+
+```text
+PASTE_ONE_MODEL_ID_FROM_THE_WIZARD
+```
+
+### AI Agent test
+
+For an AI Agent connected to a Chat Trigger, a common prompt expression is:
+
+```text
+{{ $json.chatInput }}
+```
+
+Or use this fixed prompt for the first connection test:
+
+```text
+Reply with exactly: bridge works
+```
+
+Connect the OpenAI Chat Model to the AI Agent's model input, run the workflow,
+and confirm the response before attaching tools or memory.
+
+### Basic LLM Chain test
+
+Use this fixed **Prompt** first:
+
+```text
+Reply with exactly: bridge works
+```
+
+For data supplied by an earlier node, a simple expression is:
+
+```text
+{{ $json.prompt }}
+```
+
+Connect the OpenAI Chat Model to the Basic LLM Chain's model input and execute
+the chain.
+
+## 3. HTTP Request node
+
+The HTTP Request recipe calls the bridge directly and does not need the n8n
+OpenAI credential.
+
+### Copy-paste fields
+
+Method:
+
+```text
+POST
+```
+
+URL:
+
+```text
+http://n8n-openai-oauth:10531/v1/responses
+```
+
+Authentication:
+
+```text
+None
+```
+
+Header 1 name:
+
+```text
+Authorization
+```
+
+Header 1 value:
+
+```text
+Bearer local-only
+```
+
+Header 2 name:
+
+```text
+Content-Type
+```
+
+Header 2 value:
+
+```text
+application/json
+```
+
+JSON body:
+
+```json
+{
+  "model": "PASTE_ONE_MODEL_ID_FROM_THE_WIZARD",
+  "input": "Reply with exactly: bridge works"
+}
+```
+
+Enable **Send Headers** and **Send Body**, select a JSON body, and paste the
+object above.
+
+### Importable cURL version
+
+The n8n HTTP Request node can import a cURL command. Replace only the model
+placeholder:
+
+```bash
+curl --request POST \
+  --url http://n8n-openai-oauth:10531/v1/responses \
+  --header 'Authorization: Bearer local-only' \
+  --header 'Content-Type: application/json' \
+  --data '{
+    "model": "PASTE_ONE_MODEL_ID_FROM_THE_WIZARD",
+    "input": "Reply with exactly: bridge works"
+  }'
+```
+
+The placeholder header is included because it matches OpenAI-compatible
+client behavior. It is not a real API credential.
+
+### Expression-driven HTTP body
+
+After the fixed test succeeds, switch the entire JSON body field to
+**Expression** mode and paste:
+
+```javascript
+={{ {
+  model: "PASTE_ONE_MODEL_ID_FROM_THE_WIZARD",
+  input: $json.prompt
+} }}
+```
+
+This reads the `prompt` property from the item produced by the previous node.
+
+## Related official n8n documentation
+
+- [OpenAI credentials](https://docs.n8n.io/integrations/builtin/credentials/openai/)
+- [OpenAI Chat Model](https://docs.n8n.io/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.lmchatopenai/)
+- [OpenAI Chat Model source](https://github.com/n8n-io/n8n/blob/master/packages/%40n8n/nodes-langchain/nodes/llms/LMChatOpenAi/LmChatOpenAi.node.ts)
+- [AI Agent](https://docs.n8n.io/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.agent/)
+- [Basic LLM Chain](https://docs.n8n.io/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.chainllm/)
+- [HTTP Request](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.httprequest/)