refactor: rename skill 'inkreach-teable-ops' -> 'inkreach-teable'

Rename the skill directory and update all references (SKILL.md frontmatter name, AGENTS.md, design doc, install.sh). Git tracks this as a rename so history is preserved.
2026-08-05 10:35:04 +08:00
parent 3810c33d69
commit d3790ab856
12 changed files with 2027 additions and 4 deletions
@@ -0,0 +1,87 @@
+# Instance Access
+
+How to reach the deployed inkreach-teable instance, acquire credentials, and
+verify health. This file describes the **reference deployment** — adapt
+endpoint/ports for your own deployment.
+
+## Connection
+
+| Service | URL / Port | Mode | Purpose |
+|---------|-----------|------|---------|
+| Backend API | `http://localhost:3000` | production (`NODE_ENV=production`) | REST API, automation engine, websocket |
+| Frontend | `http://localhost:3002` | production | End-user web UI (Next.js) |
+| PostgreSQL | `localhost:5432` | — | Database (db: `teable`, user: `teable`) |
+| Redis | `localhost:6379` | — | BullMQ queue for automation runs, distributed lock |
+
+- The frontend reads `SOCKET_PORT=3000` from `.env` to point its websocket at the backend. Don't let it fall back to `3001`.
+- End users browse `:3002`. The backend `:3000` is the API only (`BACKEND_SKIP_NEXT_START=true` disables the embedded Next server).
+
+## Health Checks
+
+```bash
+# Backend API up?
+curl -s -o /dev/null -w '%{http_code}' http://localhost:3000/api/auth/signin -X POST \
+  -H 'Content-Type: application/json' -d '{}'   # expect 401 (endpoint exists, bad creds)
+
+# Frontend up?
+curl -s -o /dev/null -w '%{http_code}' http://localhost:3002   # expect 307 or 200
+
+# Ports listening?
+ss -tlnp | grep -E ':3000|:3002|:5432|:6379'
+```
+
+If `:3000` is unreachable but systemd shows `active`, the worker likely OOM-crashed while the `pnpm` parent stayed alive:
+```bash
+systemctl --user stop teable-backend.service
+pkill -9 -f 'dist/index.js'
+systemctl --user start teable-backend.service
+```
+
+## Acquiring a PAT (Personal Access Token)
+
+The CLI authenticates with a PAT (`teable_{id}_{encryptedSign}`). Two ways to get one:
+
+### Option A — via the CLI (needs a session cookie or existing token)
+```bash
+inkreach-teable auth token create --name my-cli \
+  --scopes automation|read,automation|create,automation|update,automation|delete,table|read,record|read,record|create,record|update \
+  --base-ids bseXXX --expires 2099-12-31
+# → prints full token ONCE
+```
+Note: `auth token list/create` may require a **session** (browser login) rather than a PAT — if you get 403, use Option B.
+
+### Option B — via the web UI (recommended for the first token)
+1. Log in to `http://localhost:3002` as an admin.
+2. User menu → **Settings** → **Personal Access Tokens**.
+3. Create a token with scopes: `automation|*`, `table|*`, `record|*`, `field|*`, `view|*` as needed. Limit to the base if desired.
+4. Copy the `teable_xxx_yyy` string.
+
+### Configure the CLI
+```bash
+inkreach-teable auth login --endpoint http://localhost:3000 --token <PAT> --base-id bseXXX
+inkreach-teable auth status   # verify
+```
+
+## Reference Credentials (local dev)
+
+> Never commit real secrets. The reference dev instance uses:
+> - Admin: `hr_admin@xingchen.tech` / (ask maintainer) — for browser login only.
+> - Base: `bseeZR7yiDNeMPCa4CN` (人事薪资管理) — the test base with ~600 automations.
+> - Test table: `tblzPOXQvUruQosKNP5` (has button fields for automation testing).
+
+For CLI use, **always prefer a PAT** over the admin password.
+
+## Permissions
+
+- PAT scope ∩ base role = effective permission. To manage automations you need `automation|read/create/update/delete` scopes **and** a role of editor+ on the base.
+- Roles: owner (all), creator (all on the base), editor (read/create/update), commenter (read), viewer (read).
+- Workflows auto-create an internal token on activation (name `workflow:{id}`, scope limited to table/record read+write) — used by action nodes, not for CLI auth.
+
+## Troubleshooting Access
+
+| Symptom | Fix |
+|---------|-----|
+| `401 Unauthorized` | Token wrong/expired → recreate PAT, `auth login` again |
+| `403 Forbidden` | Token lacks scope, or base role too low → widen scopes / raise role |
+| `404 Base not found` | Wrong base id, or endpoint points to a different instance → `auth status`, check `--base-id` |
+| Connection refused | Backend down → health check, restart service (see [development.md](development.md)) |