{"id":50402512,"url":"https://github.com/xtrape-com/xtrape-capsule-docs","last_synced_at":"2026-05-31T00:03:23.661Z","repository":{"id":355696429,"uuid":"1225431050","full_name":"xtrape-com/xtrape-capsule-docs","owner":"xtrape-com","description":"The docs for xtrape capsule ","archived":false,"fork":false,"pushed_at":"2026-05-30T21:46:27.000Z","size":3793,"stargazers_count":0,"open_issues_count":10,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-30T22:14:24.830Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xtrape-com.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-30T09:13:46.000Z","updated_at":"2026-05-30T21:37:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/xtrape-com/xtrape-capsule-docs","commit_stats":null,"previous_names":["xtrape-com/xtrape-capsule-docs"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/xtrape-com/xtrape-capsule-docs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xtrape-com%2Fxtrape-capsule-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xtrape-com%2Fxtrape-capsule-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xtrape-com%2Fxtrape-capsule-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xtrape-com%2Fxtrape-capsule-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xtrape-com","download_url":"https://codeload.github.com/xtrape-com/xtrape-capsule-docs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xtrape-com%2Fxtrape-capsule-docs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33714036,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-31T00:03:22.541Z","updated_at":"2026-05-31T00:03:23.639Z","avatar_url":"https://github.com/xtrape-com.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\nstatus: implemented\naudience: ai-coding-agents\nstability: stable\nlast_reviewed: 2026-05-05\ncanonical_language: en\nrepository_role: private-design-source-of-truth\n---\n\n# xtrape-capsule Design Documentation\n\n\u003e **Status:** Private design documentation and implementation guidance  \n\u003e **Audience:** founders, architects, maintainers, and AI coding agents  \n\u003e **Public documentation:** `xtrape-capsule-site`  \n\u003e **Stability:** Documents may include drafts, accepted decisions, implementation notes, roadmap ideas, and commercial planning. Public-facing content must be extracted and rewritten before being published.\n\nThis repository is the private design knowledge base for the Xtrape Capsule product family.\n\nIt contains architecture notes, ADRs, specification drafts, implementation guidance, internal planning materials, and AI coding agent context.\n\nFor public-facing product documentation, quick start guides, SDK guides, and product positioning, use `xtrape-capsule-site`.\n\nEnglish documents are canonical unless a document explicitly states otherwise. Chinese translation files marked as draft or machine-assisted are not authoritative.\n\n## Repository Role\n\n- **Private source of design truth:** architecture, ADRs, specs, implementation guidance, internal planning.\n- **Not public product narrative:** do not copy private text directly into public docs.\n- **Public extraction target:** stable, approved content should be rewritten into `xtrape-capsule-site` using `PUBLIC_EXTRACTION_GUIDE.md`.\n- **AI coding context:** coding agents should start with `AI_READING_GUIDE.md` and follow the authority order defined there.\n\n\n## Maintenance Guides\n\n- `AI_READING_GUIDE.md` — authority order and required reading for AI coding agents.\n- `PUBLIC_EXTRACTION_GUIDE.md` — safe process for rewriting private content into public docs.\n- `SENSITIVE_CONTENT_CHECKLIST.md` — scan terms and review checklist before public extraction.\n- `REPO_MAP.md` — directory roles and authority map.\n- `DOCS_MAINTENANCE.md` — formatting, metadata, and link-check guidance.\n\n## 1. Current Focus\n\nThe current implementation focus is:\n\n```text\nCE v0.1 / Community Edition Prototype\n```\n\nCE v0.1 should deliver a lightweight, open-source, self-hosted prototype that proves the core Capsule governance loop:\n\n```text\nAgent registration\n    ↓\nService report\n    ↓\nHeartbeat and health\n    ↓\nConfig visibility\n    ↓\nPredefined action request\n    ↓\nCommand polling\n    ↓\nCommand result\n    ↓\nAudit log\n```\n\nCE v0.1 should use:\n\n- Opstage Backend;\n- Opstage UI;\n- SQLite persistence;\n- local admin authentication;\n- Node.js Embedded Agent SDK;\n- Node.js demo Capsule Service;\n- simple Docker or Docker Compose deployment.\n\nEE and Cloud are future tracks. They should guide extension-point design, but they must not expand the CE v0.1 implementation scope.\n\n## Current Planning Tracks\n\nImplementation focus:\n\n- `v0.1 Public Review / Public Preview readiness`\n\nNear-term planning:\n\n- `v0.2 Developer Experience \u0026 Runtime Maturity`\n\nFuture roadmap:\n\n- `v0.3 Capsule Events and Capability Metadata`\n- `v0.4 Capsule Bus Experimental`\n- `v0.5 Capsule Catalog`\n- `v0.6 Capsule Registry`\n- `v0.7 Private Capsule Marketplace`\n- `v1.0 CE Stable and Ecosystem Foundation`\n\nThese future roadmap items should guide extension-point design, but must not expand the current v0.1/v0.2 implementation scope unless explicitly promoted into an implementation issue.\n\n---\n\n## 2. Documentation Structure\n\nRecommended reading order:\n\n```text\nxtrape-capsule-docs/\n├── README.md\n├── 01-capsule/\n├── 02-specs/\n├── 03-editions/\n├── 04-opstage/\n├── 05-agents/\n├── 06-runtimes/\n├── 07-roadmap/\n├── 08-decisions/\n├── 09-contracts/\n└── 10-implementation/\n```\n\nEach directory has its own `README.md` that defines the local reading order and implementation relevance.\n\n---\n\n## 3. Directory Guide\n\n### 3.1 `01-capsule/`\n\nDefines the core domain concepts:\n\n- Capsule Service overview;\n- Capsule Service concept;\n- Capsule Service vs. microservice;\n- domain model;\n- design principles.\n\nRead this first to understand what a Capsule Service is and why Opstage governs it through Agents.\n\n### 3.2 `02-specs/`\n\nDefines shared cross-edition specifications:\n\n- Capsule Manifest;\n- Capsule Management Contract;\n- Agent Registration;\n- Health;\n- Action;\n- Config;\n- Command;\n- AuditEvent;\n- Status Model.\n\nThese specifications should remain stable across CE, EE, and Cloud. CE v0.1 may implement only the required subset, but\nit should not introduce concepts that conflict with the long-term specs.\n\n### 3.3 `03-editions/`\n\nDefines edition boundaries:\n\n```text\n03-editions/ce/      current implementation target\n03-editions/ee/      future private enterprise edition\n03-editions/cloud/   future hosted SaaS edition\n```\n\nOnly CE documents marked as implementation target should be treated as current development requirements.\n\n### 3.4 `04-opstage/`\n\nDefines the Opstage runtime governance subsystem:\n\n- Opstage overview;\n- UI;\n- Backend;\n- Agent integration;\n- Command and Action model;\n- Audit model;\n- Observability roadmap.\n\nOpstage is the first concrete governance platform for Capsule Services.\n\n### 3.5 `05-agents/`\n\nDefines the Agent system:\n\n- Agent overview;\n- Embedded Agent;\n- future Sidecar Agent;\n- future External Agent;\n- Node Agent SDK;\n- Agent permission model.\n\nCE v0.1 focuses only on the Node.js Embedded Agent SDK.\n\n### 3.6 `06-runtimes/`\n\nDefines runtime integration:\n\n- runtime overview;\n- Node.js Runtime as the CE implementation target;\n- Java Runtime planning;\n- Python Runtime planning.\n\nCE v0.1 focuses only on Node.js. Java and Python are future planning tracks.\n\n### 3.7 `07-roadmap/`\n\nDefines product and engineering sequencing:\n\n- version roadmap;\n- CE roadmap;\n- EE roadmap;\n- Cloud roadmap.\n\nUse this section to avoid mixing current CE requirements with future commercialization plans.\n\n### 3.8 `08-decisions/`\n\nDefines accepted architecture and product decisions:\n\n- CE v0.1 implementation baseline;\n- API namespace convention;\n- Command and Action lifecycle;\n- security defaults;\n- technology stack decision.\n\nAccepted decision records should be treated as current implementation constraints when older documents still contain conflicting planning details.\n\n### 3.9 `09-contracts/`\n\nDefines CE v0.1 implementation contracts:\n\n- OpenAPI contract for Admin, Agent, and System APIs;\n- Prisma schema baseline for persistence;\n- contract priority rules for implementation.\n\nUse this section when building Backend, UI API clients, Agent SDK clients, tests, and database migrations.\n\n\n### 3.10 `10-implementation/`\n\nDefines CE v0.1 implementation planning:\n\n- monorepo structure;\n- Backend scaffold plan;\n- UI scaffold plan;\n- Node Agent SDK scaffold plan;\n- demo Capsule Service plan;\n- implementation sequence.\n\nUse this section after ADRs and contracts are accepted, when starting implementation work.\n\n---\n\n## 4. CE v0.1 Implementation Target\n\nCE v0.1 should include:\n\n```text\nOpstage Backend\nOpstage UI\nSQLite persistence\nlocal admin login\nregistration token\nAgent token authentication\nNode.js Embedded Agent SDK\nNode.js demo Capsule Service\nAgent heartbeat\nservice manifest report\nhealth report\nconfig metadata visibility\npredefined action metadata\naction request from UI\nCommand creation\ncommand polling\nCommandResult reporting\nbasic AuditEvents\nDashboard summary\nSystem health endpoint\nDocker quick start\n```\n\nCE v0.1 should be useful as open source. It should not be an intentionally crippled trial.\n\n---\n\n## 5. CE v0.1 Non-Goals\n\nCE v0.1 should not implement:\n\n```text\nTenant system\nOrganization system\nbilling\nsubscription\nusage metering\nenterprise RBAC\nSSO / OIDC / LDAP / SAML\nPostgreSQL/MySQL requirement\nRedis requirement\nQueue requirement\nKubernetes requirement\nAgent Gateway\nSidecar Agent\nExternal Agent\nJava Agent SDK\nPython Agent SDK\nGo Agent SDK\nfull observability platform\nalert rule engine\nsecret vault\nlicense enforcement\nremote shell\narbitrary script execution\n```\n\nThese are future roadmap items or intentionally excluded from the first implementation.\n\n---\n\n## 6. Development Rules\n\n### 6.1 Build CE first\n\nCurrent development should serve CE v0.1 unless a document explicitly marks a feature as current scope.\n\n### 6.2 Keep CE lightweight\n\nCE v0.1 should prefer:\n\n- SQLite by default;\n- local admin authentication;\n- HTTP heartbeat;\n- command polling;\n- Node.js Embedded Agent SDK;\n- single default Workspace;\n- single-node deployment;\n- basic AuditEvents;\n- basic governance visibility.\n\nAvoid Kubernetes, distributed queues, full observability stacks, enterprise RBAC, SSO, tenancy, and billing in CE v0.1.\n\n### 6.3 Reserve extension points without implementing future systems\n\nCE should reserve low-cost extension fields and concepts such as:\n\n```text\nworkspaceId\nagentMode\nruntime\nprotocolVersion\ncapabilities\nmetadataJson\nsecretRef\nCommandType\nAuditEvent actor/resource fields\n```\n\nThe rule is:\n\n```text\nReserve shape, not scope.\n```\n\n### 6.4 Use Agent-based governance\n\nOpstage should not directly control arbitrary services.\n\nCapsule Services enter governance through registered, authenticated Agents.\n\nCE v0.1 actual flow:\n\n```text\nNode.js Capsule Service\n    ↓ Node.js Embedded Agent SDK\nOpstage Backend\n    ↓ Admin API\nOpstage UI\n```\n\n### 6.5 Execute only predefined actions\n\nOperations must be modeled as predefined actions, durable Commands, CommandResults, and AuditEvents.\n\nCE v0.1 must not provide remote shell or arbitrary script execution.\n\n### 6.6 Protect secrets\n\nOpstage should store governance metadata, not raw secrets by default.\n\nUse:\n\n```text\nsecretRef\nmasked values\nsanitized summaries\n```\n\nDo not log or store raw registration tokens, Agent tokens, passwords, cookies, OAuth tokens, API keys, private keys, or browser sessions.\n\n---\n\n## 7. Recommended Reading Path for CE v0.1\n\nRecommended path for developers and AI coding agents:\n\n```text\nREADME.md\n01-capsule/README.md if present, otherwise 01-capsule/00-overview.md\n01-capsule/01-capsule-service-concept.md\n08-decisions/README.md\n08-decisions/0001-ce-v01-implementation-baseline.md\n08-decisions/0002-api-namespace-convention.md\n08-decisions/0003-command-action-lifecycle.md\n08-decisions/0004-security-defaults.md\n08-decisions/0005-technology-stack-decision.md\n09-contracts/README.md\n09-contracts/openapi/opstage-ce-v0.1.yaml\n09-contracts/prisma/schema.prisma\n09-contracts/prisma/prisma.config.ts\n10-implementation/README.md\n10-implementation/00-repository-structure.md\n10-implementation/05-implementation-sequence.md\n02-specs/README.md\n02-specs/03-agent-registration-spec.md\n02-specs/07-command-spec.md\n03-editions/README.md\n03-editions/ce/README.md\n03-editions/ce/01-ce-scope.md\n03-editions/ce/02-ce-mvp.md\n03-editions/ce/03-ce-architecture.md\n03-editions/ce/13-ce-v01-implementation-checklist.md\n04-opstage/README.md\n04-opstage/02-opstage-backend.md\n04-opstage/01-opstage-ui.md\n04-opstage/04-command-and-action-model.md\n05-agents/README.md\n05-agents/04-node-agent-sdk.md\n05-agents/05-agent-permission-model.md\n06-runtimes/README.md\n06-runtimes/01-node-runtime.md\n07-roadmap/README.md\n07-roadmap/01-ce-roadmap.md\n```\n\n---\n\n## 8. Edition Status\n\n| Edition | Status | Purpose |\n|---|---|---|\n| CE | Current implementation target | Lightweight open-source self-hosted edition |\n| EE | Future planning | Private enterprise commercial edition |\n| Cloud | Future planning | Hosted SaaS edition |\n\n---\n\n## 9. First Milestone\n\nThe first milestone is:\n\n```text\nCE v0.1 Prototype\n```\n\nIt should demonstrate:\n\n- local Opstage startup;\n- local admin login;\n- registration token creation;\n- Node.js demo service registration;\n- Agent heartbeat;\n- Capsule Service visibility;\n- health visibility;\n- config metadata visibility;\n- predefined action visibility;\n- `echo` action execution;\n- `runHealthCheck` action execution;\n- CommandResult visibility;\n- AuditEvent visibility;\n- Docker quick start.\n\n---\n\n## 10. Summary\n\nThis documentation set should guide implementation toward a small, useful, safe, and extensible CE v0.1 first.\n\nThe most important repository-level rule is:\n\n\u003e Build the CE governance kernel first, keep future EE and Cloud as extension tracks, and preserve the Agent-based, predefined-action, secretRef-safe model across all editions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxtrape-com%2Fxtrape-capsule-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxtrape-com%2Fxtrape-capsule-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxtrape-com%2Fxtrape-capsule-docs/lists"}