Family Tutor

Family Tutor is a customer-ready foundation for a personalized family AI tutor. Each child has a separate ChatGPT Project/thread and private Discord destination; parents receive concise learning telemetry rather than routine transcripts. The family owns its ChatGPT account, Projects, and Discord server. Family Tutor owns the extension, hosted connectivity/routing, shared Discord bot integration, setup, support, and any explicitly entitled premium tools.

This is not an education-content SaaS, curriculum marketplace, or replacement for the customer's ChatGPT intelligence. The hosted components are intentionally thin infrastructure. No local MCP federation, per-family domain, or raw provider/channel routing is part of the commercial boundary.

What is implemented

• packages/core: authenticated family/session provisioning, logical child/parent routing, provider binding storage, suspension, revocation, and transcript-free state validation.
• packages/discord-adapter: shared Discord transport boundary. It accepts authenticated logical destinations and resolves provider IDs only inside the trusted adapter, with audit and rate-limit hooks.
• packages/hosted-mcp-adapter: authenticated /mcp service with core/premium tool entitlements, scope checks, rate limits, redacted audit events, and /healthz//readyz endpoints.
• packages/onboarding: resumable, no-JSON-editing setup flow for ChatGPT Developer Mode, the shared bot, logical destinations, child Projects, extension health, and same-origin acceptance probes.
• packages/integration: canonical hosted product composition. It connects provisioning, onboarding, extension readiness, hosted MCP, Discord delivery, lifecycle controls, and /healthz//readyz in one runtime path.
• skills/family-tutor/extension: unpacked Chrome Manifest V3 adapter for deterministic child-to-Project binding, recovery, and diagnostics.
• skills/family-tutor/: reusable local tutoring runtime for an operator's private instance; real family data belongs only under ignored runs/.
• site/: dependency-free promotion site for the five-family founding pilot.

The central safety invariant is: authenticate the family, authorize the scope, resolve a logical destination, then touch a provider ID. Model/tool callers must never supply a raw Discord channel ID or another family's identifier.

Documentation map

Start with docs/architecture.md for the shared service boundaries, then use docs/onboarding.md for the customer path. docs/tenant-routing.md, docs/discord-adapter.md, and docs/hosted-mcp-adapter.md define the security contracts. docs/extension.md covers browser release and recovery behavior; docs/operations.md covers deployment, state, logging, backup, and incidents. Pilot execution is in docs/launch-checklist.md and docs/support-runbook.md; privacy communication is in docs/privacy-consent.md.

Development and verification

The repository is deliberately split into small, independently testable packages. Run the full release gate from the root:

npm run check
git diff --check

npm run check runs package checks, integration isolation tests, operations redaction tests, MCP/Discord adapter tests, onboarding tests, and extension syntax/protocol tests. The production release gate also requires a real Discord acceptance run with distinct probes for each child; service health or direct backend probes alone are insufficient. See e2e.md.

The product-level synthetic gate can be run independently with npm run check:product; it is also included in npm run check.

Start the integrated hosted process with:

npm run start:product

The default Discord bot boundary is serverless on Cloudflare. The cloudflare/discord-setup-worker Worker owns Discord install/OAuth and outbound REST delivery; its DiscordGateway Durable Object owns the Discord Gateway WebSocket and forwards MESSAGE_CREATE events through the authenticated NeoY MCP endpoint. NeoY federates the loopback-only Family Tutor MCP locally, so the Tutor MCP itself does not need a second authentication layer.

Private local instance

The local tutoring runtime is an operator/development path, not the hosted multi-family service. Keep family configuration, Discord IDs, credentials, and runtime state under ignored runs/family/:

node skills/family-tutor/scripts/init-instance.mjs runs/family
node skills/family-tutor/scripts/doctor.mjs runs/family
node skills/family-tutor/scripts/service.mjs start runs/family

New private/local instances use the browser-workspace skill and discord.mode: "cloudflare" by default. On startup the local Family Tutor service calls browser-workspace status, loads the returned product admin helper, and ensures the product-owned Tutor workspace through that API; learner session start/exec/stop remains on the normal Browser Workspace CLI. The service also exposes a loopback-only MCP provider for NeoY federation. Discord Gateway connectivity and the Discord bot token live on Cloudflare, not in the local PM2 process. Existing browserBridge and discord.mode: "local" instances remain migration paths; old neoyTutor config is automatically migrated to Browser Workspace semantics.

Never commit real family configuration, learner details, transcripts, tokens, or runtime state. There is no learner AGENTS.md in the Browser Workspace path. ChatGPT Project-only memory and the persistent learner thread provide continuity; Family Tutor stores only learner/project/thread binding metadata.

Commercial deployment boundary

Deploy the hosted MCP and shared Discord adapters behind TLS, a transactional provisioning store, platform-managed secrets, and process supervision. The repository contains implementation contracts and a static promotion site; it does not contain production credentials, DNS ownership, legal approval, or a claim that Cloudflare has already been deployed. See docs/promotion-site.md for the intended family-tutor.qili2.com Pages deployment and its owner-controlled blockers.