mirror of https://github.com/turnstonelabs/turnstone.git synced 2026-08-12 23:12:23 -06:00

Files

T

Patrick Buckley 471d1a3311 docs: audit documentation for 1.4 / 1.5 state

Systematic pass over every doc under docs/, the root-level README /
QUICKSTART / CONTRIBUTING, and the PlantUML diagrams.  Memory and docs
had drifted against the code since 1.2 — this catches them up to the
1.4.0 release and the 1.5.0a1 experimental line.

User-facing fixes
- README: fix broken docs/mcp.md link (→ mcp-registry.md); channel
  gateway entry reflects shipped Discord + Slack adapters instead of
  "Slack/Teams planned"; diagrams table mentions both.
- QUICKSTART: docs/*.md relative links were wrong from the repo root;
  wizard version bumped from 0.5.4.
- CONTRIBUTING: add dev extra plus the ruff / mypy / pytest commands
  we actually expect before push.

Reference docs
- architecture.md: 19 tool schemas (was 15), 18 admin tabs (was 14),
  turnstone-bootstrap added to entry-points table, OpenAI provider
  file split (chat/responses/common) documented, 38 SDK event
  dataclasses (was 27 and referenced deleted mq/protocol.py), Slack
  adapter + multi-adapter gateway, plan_agent/task_agent naming,
  governance admin-panel rewrite.
- api-reference.md: full attachment endpoints (POST/GET/content/
  DELETE on /v1/api/workstreams/{ws_id}/attachments) plus the
  multipart mode on POST /v1/api/workstreams/new.
- channels.md: Slack Setup section (Socket Mode app creation, OAuth
  scopes, tokens), Slack CLI/env reference in config table, combined-
  adapter architecture diagram.
- console.md: 18-tab listing (was 13) with Channels/Models/Nodes/TLS
  descriptions and ConfigStore live-edit note.
- docker.md: Slack env vars block; image entry-point list now
  includes turnstone / turnstone-bootstrap.
- sdk.md: attachments methods on the server client, attachments
  example (upload-then-send and at-creation), event count fixed.
- releasing.md: four-track table (stable/1.0, 1.3, 1.4 + main 1.5);
  promotion workflow uses 1.5 / 1.6 numbering.
- settings.md: plan_model / task_model / plan_effort / task_effort
  overrides section.
- governance.md: skill naming (/skill, `skill` field — not /template),
  Prompts/Judge tabs called out.
- security.md: two-token-types wording; src claim values match the
  AuthResult source strings actually emitted.
- mcp-registry.md: SDK package name is @turnstone/sdk.
- tools.md: plan / task renamed to plan_agent / task_agent in the
  section headings and summary table; primary-key table matched.
- design/consistent-hash-ring.md: dead direct-http-transport.md
  pointer redirected to architecture.md.

Diagrams
- 02-package-structure: drop phantom chat.py entry point, add admin
  and bootstrap, add slack/bot.py, rename channels/gateway.py →
  channels/cli.py.
- 16-channel-architecture: Slack is no longer "(future)", add a
  SlackBot class and the slack-bolt Socket Mode edges; wire the new
  bot into ChannelService.  PNGs regenerated from both puml sources.

2026-04-16 16:01:24 -07:00

3.3 KiB

Raw Blame History

Bootstrap Wizard

Interactive, AI-guided setup for Turnstone deployments. Instead of manually editing .env files and reading deployment docs, the wizard walks you through every decision conversationally and generates all the config files for you.

Quick Start

turnstone-bootstrap

That's it — no flags, no arguments. The wizard prompts for everything.

How It Works

Pick a model — Choose OpenAI, Anthropic, or a local/vLLM endpoint to power the wizard. Local endpoints auto-detect available models.
Answer questions — The AI walks you through deployment mode, LLM provider, database, authentication, ports, and optional features.
Review generated files — Each file is previewed before writing. You confirm or reject every write.
Start the stack — The wizard prints the exact docker compose command and a setup.sh script to create your first admin user, roles, and policies.

What Gets Generated

File	Purpose
`.env`	All environment variables for `compose.yaml`
`setup.sh`	Post-start script: creates admin user, roles, tool policies, prompt templates via the API
`docker-compose.override.yaml`	Only if customizations beyond env vars are needed

Requirements

Python 3.11+ with turnstone installed (pip install turnstone)
An LLM API key — for the wizard itself (OpenAI, Anthropic, or a local model). This can differ from the LLM your deployment will use.
Docker & Docker Compose — needed to run the stack. The wizard detects whether Docker is installed and gives platform-specific install instructions if it's missing. You can still generate config files without Docker.

Deployment Modes

The wizard supports two deployment modes:

Single-node production (docker compose --profile production up) — 1 server + console + PostgreSQL. Good for most use cases.
Multi-node cluster (docker compose --profile cluster up) — 10-node server fleet + console + PostgreSQL. For high-throughput or HA deployments.

Example Session

$ turnstone-bootstrap

 Turnstone Bootstrap Wizard  v1.5.0
 ────────────────────────────────────────────────

 Which provider for this wizard?
   [1] OpenAI
   [2] Anthropic
   [3] OpenAI-compatible (local/vLLM)

 > 3

 Base URL [http://localhost:8000/v1]:
 API key (press Enter for 'none'):

 Querying http://localhost:8000/v1 for available models...
 Found model: Qwen/Qwen3-32B

 Connected to Qwen/Qwen3-32B. Handing off to AI assistant...

> (AI walks you through the rest interactively)

Tips

Re-run safely — running the wizard again detects your existing .env and offers to update it rather than overwriting.
Duplicate writes are skipped — if the LLM tries to write the same file twice with identical content, it's silently ignored.
Type quit to exit at any time during the conversation.
Ctrl+C is handled gracefully — press once to interrupt, twice to exit.

3.3 KiB Raw Blame History