# Crystal AgentOS Community Edition

**A local, documentation-first foundation for agents and the people who direct them.**

AgentOS gives a project a repeatable path from its current state to a verified change: project dossier → roadmap → documented stage → implementation → checks → updated documentation. A short intake selects only the relevant document layers. The CLI keeps the task, source, documents and check evidence bound to the same stage; ordinary read-only questions bypass intake entirely. Native hooks are excluded; explicit CLI checks do not intercept arbitrary tools.

This is the canonical public repository: [crystalstrategysup-prog/agent-os](https://github.com/crystalstrategysup-prog/agent-os). This source declares candidate `0.8.0rc2` (Python distribution version `0.8.0rc2`). It is a local publication candidate until the canonical tag, release object and uploaded assets are independently read back. It is separate from any maintainer's private runtime, infrastructure and personal data.

Visit the [public project website](https://crystalstrategy.ru/agent-os/), read the [changelog](CHANGELOG.md), or open an [issue](https://github.com/crystalstrategysup-prog/agent-os/issues) with a bug or technical review. Verify tag, release asset and website deployment separately.

## Indexed results library

Stable 0.7.1 includes the reviewed indexed results, coordinator and model-policy source contracts. Read [the indexed results format and limits](docs/INDEXED_HANDOFF.md). Source implementation is separate from live installation; physical session cleanup is not implemented.

## Two physical layers

| Foundation, maintained here | User overlay, owned by the user |
| --- | --- |
| Python code, universal rules, schemas, templates, skills and docs | Configuration, knowledge references, optional 0 / 1 / N profiles, local state, secrets and extensions |
| Installed in a virtual environment or an immutable release directory | One separate folder, default `~/.agentos-user` |
| Updated or rolled back by selecting a verified release | Preserved on core update; imported and migrated only through explicit guarded commands |

See [Foundation ↔ Overlay](docs/FOUNDATION_OVERLAY.md) for versioning, conflicts and recovery. Project documents remain in their projects; the overlay indexes them without copying every project into the core.
Project lifecycle records in a project's `.agentos/` directory are a separate local state surface and are excluded from public source exports.

Profiles are optional files under the user overlay. `agentos profiles inventory` reports their hashes and overlaps; `profiles select` activates none, one, or all in an explicit order. Conflicting values need an owner choice. `profiles interview` prefills observed device facts and asks about missing user fields. Editing or removing a profile leaves the installed foundation unchanged.

## Source verification and installation

Python 3.11+ is required. Review the exact source and diff, run the local tests and compare
package resources before integration. A version string alone does not prove
publication or activation. See [Install and update](docs/INSTALL_UPDATE.md)
for the separately authorized offline flow, overlay preservation and no-hook rollback.
No global hooks, model/auth or client security changes are part of this release.

## Ordinary read-only requests

Answer questions, search, inspect code and discover authorized API capabilities directly.
No registration, answers file, profile interview, observe receipt or closeout is needed.
Optional `agentos workflow route --kind audit` explains the route without reading overlay
or changing files; calling it is not a prerequisite for answering a question.

## Connection scenarios

The public foundation includes an indexed catalog of versioned connection
scenarios. `agentos setup list` shows the available scenarios;
`agentos setup show telegram-owner-inbox` opens the owner file inbox card. The catalog
covers Telegram MTProto, Telegram Business, owner file inbox and SSH/VNC over SSH. All cards are
`guide_only`: the commands return guidance and do not connect to devices,
log in, create bots, grant rights or read user secrets. The SSH/VNC card starts
with a known route and distinguishes transport from authenticated access. An
interactive installer or provider adapter requires its
own implementation and authority. See the [authoring and maintenance
protocol](docs/SETUP_SCENARIOS.md) and the [index](src/agent_os/resources/setup-scenarios/index.json).

For one existing SSH alias, `agentos setup probe ssh-vnc --host ALIAS` plans
without network access; `--apply` checks authenticated SSH and optional RFB
transport with a temporary private forward. It leaves VNC login and the desktop
frame unverified. See the [tested field procedure](docs/SSH_VNC_FIELD_GUIDE.md).

## Work continuity

The [work-continuity guide](docs/WORK_CONTINUITY.md) and packaged passport
template help a user preserve a compact index of active projects, current
handoffs, source and data locations, and recovery checks. A filled passport is
private user knowledge. The template does not back up databases or prove that
a cloud copy can be restored.

## Instruction routing

Keep inherited project `AGENTS.md` short: define its scope, universal limits and
links to the project documents or skills that explain each topic. Read detailed
material only when the task requires it, and verify dated status against current
source or runtime evidence. A size target such as 4 KiB is editorial guidance,
not an entry or read-only gate. Reorganizing instructions is a separate project
change; a read-only request does not authorize that edit. The public foundation
stays host-neutral; owner and host details belong in the separate user overlay. See
[architecture](docs/ARCHITECTURE.md) and [process](docs/PROCESS.md).

## Start a project task

```sh
agentos project questions --root /absolute/path/to/project
agentos project init --root /absolute/path/to/new-project --name Example \
  --type platform --feature public --context context.json
agentos project enter --root /absolute/path/to/project \
  --session ACTUAL_SESSION --turn ACTUAL_TURN --answers answers.json
```

`questions` shows verified project context and only missing supplied answers. Same-scope `--resume-task` reuses previous answers except current authority; `enter --reuse-answers` makes that reuse explicit. JSON inputs accept `-` for stdin. The required documents depend on project type and changed surfaces. A new project starts with a dossier and roadmap; every product stage has its own contract and acceptance checks before code changes. `ready` rejects draft or stale documents. `check`, `assess` and `close` require current source-bound evidence plus named semantic review. Optional audit recording uses `project observe`; ordinary investigation needs no receipt. `project verify-closeout` checks whether a CLOSED result still has current evidence. The [process](docs/PROCESS.md), [documentation catalog](docs/DOCUMENTATION_CATALOG.md) and [synthetic example](tools/demo_lifecycle.py) show the full flow.

## Interfaces and boundaries

- The stdio MCP server exposes six narrow planning/status tools. `tools/list` includes versioned input and output schemas; it does not expose arbitrary shell, SSH, file contents or credentials. See [MCP contract](schemas/mcp-tools-v1.json).
- The [CLI contract](schemas/cli-contract-v1.json), [data schemas](src/agent_os/resources/schemas/) and [contracts guide](docs/CONTRACTS.md) describe the machine-readable surfaces. No HTTP server is provided, so OpenAPI is not applicable to this release.
- Codex AGENTS and namespaced skills can be integrated while preserving other owners' content. **No native hooks are created or restored.** Read back effective instructions in a fresh client session; do not claim a universal tool sandbox.
- The optional Telegram Session Hub remains owner-allowlisted and disabled by default. Read [compatibility](docs/COMPATIBILITY.md) before replacing any existing connector.
- Existing model routing, current-evidence result assessment, Full Inventory and update advisory remain available through the CLI. Their contracts and limits are in [architecture](docs/ARCHITECTURE.md), [result evidence](docs/RESULT_EVIDENCE.md), [Full Inventory](docs/FULL_INVENTORY.md) and [update checks](docs/UPDATE_CHECK.md).
- The Codex in-app Browser and Chrome remain separate documented surfaces; see [browser surfaces](docs/BROWSER_SURFACES.md). The optional [Telegram onboarding plan](docs/TELEGRAM_SESSION_HUB.md) does not require a website or transmit credentials to this repository.

## Develop and verify

```sh
python -m pip install -e '.[dev]'
python -m pytest -q
python tools/demo_lifecycle.py
python tools/verify_public.py
```

Start with the [documentation index](docs/README.md), [project dossier](docs/agentos/DOSSIER.md), [roadmap](docs/agentos/ROADMAP.md), [public workflow](docs/PROCESS.md), [source release contract](docs/agentos/RELEASE.md), [architecture](docs/ARCHITECTURE.md) and [developer onboarding](docs/ONBOARDING.md). The [changelog](CHANGELOG.md), [release policy](docs/RELEASE.md) and [public language policy](docs/LOCALIZATION.md) state the release status and limits. GitHub Actions are not used.

Crystal AgentOS is Apache-2.0 software. Contributions and skeptical technical reviews are welcome; see [Contributing](CONTRIBUTING.md), [Security](SECURITY.md), [Governance](GOVERNANCE.md) and the [AI Stewardship Charter](STEWARDSHIP.md).

For current project handoff lookup, follow [the handoff discovery contract](docs/HANDOFF_DISCOVERY.md) and verify the selected index. Filled task handoffs remain outside the public source.

The [0.7.1 release package](docs/RELEASE_PACKAGE.md) includes reviewed opt-in adapters and operator gates. It provides no running scheduler or persistent connected bridge. Host activation, manual client reload, voice validation and owner-policy adoption remain separate authorized stages.

The historical RC3 candidate packages [metadata-only tracked directory aliases](docs/SOURCE_SYMLINKS.md). Its inherited behavior has bounded predecessor coverage; the final stable artifact must be reviewed independently. This candidate does not claim an installed, running or published runtime.

## Historical main coordinator candidate 0.7.0rc2

Use the [single coordination knowledge index](docs/COORDINATOR_KNOWLEDGE_INDEX.json) and [work-management contract](docs/WORK_COORDINATION.md). The optional synchronous Python ledger records verified receipt/review/remainder/next ownership, protects original parent acceptance and reconciles missed results/unknown effects. It launches nothing. Private persona/owner knowledge stay outside core; live adoption, publication and session cleanup remain separate.

## Guarded session launch in 0.7.1

Qualified creation now reads the exact approved Codex binary's inherited configuration and bounded model catalog before creating a thread. Actual startup metadata and harmless tool probes precede original work. [Persistent GNU Screen](docs/SCREEN_LAUNCH.md) retains the same worker, connection and thread after its caller exits. [Selected context materialization](docs/CONTEXT_BINDING.md) returns verified document bodies; it does not prove compliance. Existing clients and private owner instructions require separate adoption. No model, provider, auth, sandbox, approval or native-hook setting is changed.

## Completion and safe recovery candidate

[The completion guide](docs/COMPLETION.md) describes explicit bounded continuation, receiver fencing, independent acceptance, verified handoff and checkpoint recovery on the existing Coordinator store. This candidate does not install a scheduler or hooks. Only the scoped local POSIX registered-command adapter is qualified; remote/cloud completion and Goals activation require separate actual adapter qualification. The owner runtime and already-open sessions do not adopt source changes automatically.