Evaluate
Run a safe starting point
Use the source guide, then inspect the account-free fictional-data sample before configuring private data or an external provider.
Reference center
Everything needed to evaluate the boundary.
This is the map for developers, privacy reviewers, and agent builders. It distinguishes what source demonstrates now from what is planned or deliberately unavailable.
Current status: treat this as a source-first developer preview. The isolated sample is fictional and has no external effects. The planned
v0.7.0-beta remains blocked until its evidence and release gates are satisfied; consult the claim ledger for the authoritative status.Pick your path
Integrate
Connect an agent without granting authority
Configure the scoped local Twin MCP server, submit proposals, and let the normal policy path decide what can happen.
Review
Trace a product claim to evidence
The evidence deck and claim ledger identify the artifacts, tests, and remaining gates behind public-facing statements.
Contribute
Make an inspectable change
Read repository rules before touching the policy, safety, privacy, or release surface; use an issue or narrow pull request for feedback.
System model
The project converts signals into an explicit decision pipeline: signal → context → candidate action → policy evaluation → approval, safe route, or refusal → explanation and feedback. A model, connector, or MCP client may inform a candidate; it does not bypass the policy decision.
Architecture
Components and contracts
Repository package map, data flow, typed decision objects, storage model, and execution adapters.
Safety
Trust, spend, risk, and provenance
Policy checks, trust-tier enforcement, mandatory explanations, untrusted-origin containment, and human confirmation rules.
Operations
Run and troubleshoot the stack
Workspace commands, package structure, database/runtime expectations, and local build cautions are kept in the repository instructions.
Product
Scope and non-goals
Product boundaries, proposed behavior, and intentionally deferred work. Read it with the release ledger, not as a release promise.
Operational quick reference
These commands are for a checked-out source tree. They are useful for inspection and contribution; they do not turn the developer preview into a supported installer release.
| Goal | Command or endpoint | Expected boundary |
|---|---|---|
| Start local development | pnpm dev | API on localhost:3100 and dashboard on localhost:3200; local port preflight runs before services start. |
| Verify source changes | pnpm buildpnpm testpnpm lint | Repository checks—not evidence that an unsigned installer, signing, or release claim is ready. |
| Probe a running API | GET /api/health/liveGET /api/health/ready | Liveness means process up; readiness includes database/pool availability. See operations documentation for monitoring details. |
| Run agent endpoint | TWIN_MCP_SERVER_PORT=4444 pnpm --filter @skytwin/twin-mcp-server start | Local HTTP MCP with a scoped bearer token. The agent guide covers the safe proposal loop. |
Privacy and inference boundaries
| Route | What the project can say today | What to verify before use |
|---|---|---|
| Embedded / loopback local route | Intended local route; it does not fall through to a network provider on failure. | Runtime/model availability, device storage protections, and any local model artifact choices. |
| Configured hosted provider | An explicit network route under that provider's terms; it is not a confidential-computing claim. | Endpoint, account, data handling, retention, and the exact prompt fragments that may be sent. |
| Verified-private remote route | TrustedRouter is available for explicit interactive calls only after SkyTwin verifies fresh same-session gateway attestation and an exact-byte confidential-route receipt. Verification failure returns no content and does not fall back. NEAR AI remains unavailable. | Valid credentials and credits, live per-call evidence, pinned policy, exact request/response binding, and the current interactive-only spend boundary. |
Read the confidential-inference boundary, privacy disclosure, and TrustedRouter trust record. A provider name, portal, or signed receipt alone is not enough; the admitted SkyTwin adapter must verify the exact call.
Agent and tool protocol
MCP
Scoped local access
Endpoint setup, bearer-token handling, scopes, capability negotiation, tools, and error behavior.
External tools
Admitted tools, not arbitrary execution
MCP host configuration, transport, circuit state, and zero-trust behavior are implementation concerns with security consequences.
Minimum safe agent behavior
Request the minimum context; preserve origin/provenance; describe a candidate's target, parameters, risk, reversibility, and cost; wait for the policy outcome; and never replay an ambiguous external mutation. Full rules are in the agent guide.
Release and evidence
Do not use a version number, older installer, source branch, or a green unit test as a blanket assertion of readiness. The project tracks claims and their required evidence separately.
Claims
Release claim ledger
Current target, claim statuses, linked evidence, and blockers for the public beta.
Evidence
Launch readiness material
Release procedure and the template for recording reproducible evidence; neither substitutes for the required evidence itself.