Skip to content

Commit 888b740

Browse files
ProfRandom92ProfRandom92
committed
Polish README for CompText CLI release candidate
1 parent 416036e commit 888b740

1 file changed

Lines changed: 146 additions & 125 deletions

File tree

‎README.md‎

Lines changed: 146 additions & 125 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
11
<p align="center">
2-
<img src="assets/brand/comptext-cli-readme-header.jpg" alt="CompText CLI — CLI Runtime for Deterministic Context" width="100%">
2+
<img src="assets/brand/comptext-cli-readme-header.jpg" alt="CompText CLI - CLI Runtime for Deterministic Context" width="100%">
33
</p>
4+
45
<div align="center">
56

67
# CompText `ctxt`
78

8-
**Deterministic contract runtime for agent-friendly local review workflows.**
9+
**Deterministic local CLI runtime for agent-readable JSON contracts.**
910

1011
**Models are providers. Context is the product.**
1112

@@ -26,147 +27,114 @@ It does not execute external agents, use network, call providers, apply proposal
2627

2728
</div>
2829

29-
CompText `ctxt` v0.1.0 is a local-first Rust CLI for deterministic, schema-oriented review workflow contracts. It gives Codex, Antigravity, and human reviewers stable JSON entrypoints for startup checks, capability discovery, proposal evidence, review evidence, subagent role contracts, and validation summaries before any higher-risk action is considered.
30+
> **Safety boundary**
31+
>
32+
> `ctxt` is local-first. Network is denied by default. Provider calls are not part of the documented workflow. External agent execution is disabled. Proposal and review artifacts are evidence, not instructions to auto-apply. Subagent role contracts are available, but subagents do not execute. No MCP server implementation is claimed.
3033
31-
The current release candidate is focused on contract clarity, local evidence, and safe startup behavior. It is not an autonomous coding system, not a provider gateway, and not a remote orchestration layer.
34+
CompText `ctxt` v0.1.0 is a release candidate until the release is tagged.
3235

3336
## Table of Contents
3437

35-
- [Why CompText](#why-comptext)
36-
- [Architecture](#architecture)
37-
- [Deterministic Review Workflow](#deterministic-review-workflow)
38-
- [Safety Boundary](#safety-boundary)
39-
- [Quickstart](#quickstart)
38+
- [30-Second Explanation](#30-second-explanation)
39+
- [Install / Run](#install--run)
40+
- [Using With Codex / Antigravity](#using-with-codex--antigravity)
4041
- [Command Matrix](#command-matrix)
4142
- [Capability Matrix](#capability-matrix)
43+
- [Architecture](#architecture)
44+
- [Review Workflow](#review-workflow)
4245
- [Safety Matrix](#safety-matrix)
4346
- [Validation Evidence](#validation-evidence)
44-
- [Visual Asset Plan](#visual-asset-plan)
47+
- [Distribution / Release Channel](#distribution--release-channel)
4548
- [Roadmap](#roadmap)
4649
- [Contributing](#contributing)
4750
- [License](#license)
4851

49-
## Why CompText
52+
## 30-Second Explanation
5053

51-
Most agent workflows start with ambiguous state and only later discover whether the environment was safe, validated, or consistent. CompText flips that order:
54+
**What it is:** `ctxt` is a Rust CLI that emits deterministic JSON contracts for local agent and reviewer workflows.
5255

53-
1. expose local runtime contracts first,
54-
2. report capabilities before actions,
55-
3. keep artifacts bounded and inspectable,
56-
4. make disabled gates explicit,
57-
5. validate locally before claims,
58-
6. summarize evidence for the user.
56+
**Why it exists:** agent sessions need a reliable way to inspect startup state, supported commands, disabled gates, local artifacts, and validation evidence before making claims or attempting higher-risk work.
5957

60-
The result is a small CLI surface that helps an agent or reviewer answer: what is available, what is disabled, what evidence exists, and what local validation says.
58+
**Who uses it:** humans, Codex, Antigravity, and other local automation can call the same `ctxt --json ...` entrypoints to read the project contract surface without widening permissions.
6159

62-
## Architecture
60+
The product is the context boundary: stable inputs, explicit gates, bounded artifacts, and local validation before provider interaction is considered.
6361

64-
```mermaid
65-
flowchart LR
66-
user["User or Agent"] --> cli["ctxt CLI"]
67-
cli --> contracts["JSON contracts"]
68-
contracts --> artifacts["Local artifacts"]
69-
contracts --> validation["Validation output"]
70-
artifacts --> summary["User summary"]
71-
validation --> summary
72-
```
62+
## Install / Run
7363

74-
`ctxt` is intentionally boring at the boundary: commands produce local JSON contracts and evidence-oriented output. That makes it easier for automation to inspect state without assuming permission to mutate files, call providers, or reach the network.
64+
### Current Source Workflow
7565

76-
## Deterministic Review Workflow
66+
Run from a checked-out copy of this repository:
7767

78-
```mermaid
79-
flowchart TD
80-
readiness["startup readiness"] --> flow["startup flow"]
81-
flow --> schema["schema"]
82-
schema --> capabilities["capabilities"]
83-
capabilities --> subagents["subagents"]
84-
subagents --> proposals["proposals"]
85-
proposals --> reviews["reviews"]
86-
reviews --> workflow["review workflow"]
87-
workflow --> validate["validate --run"]
88-
validate --> summary["user summary"]
68+
```powershell
69+
cargo run --bin ctxt -- --json capabilities
8970
```
9071

91-
The review workflow is a contract-only checklist. Each command is run explicitly by the user or agent inside the allowed task scope. The workflow does not imply remote execution, hidden automation, or automatic application of recommendations.
92-
93-
## Safety Boundary
72+
Useful first checks:
9473

95-
```mermaid
96-
flowchart LR
97-
contracts["Allowed read-only contracts"] --> self["self report"]
98-
contracts --> schema["schema"]
99-
contracts --> capabilities["capabilities"]
100-
contracts --> startup["startup readiness and flow"]
101-
contracts --> evidence["proposal and review evidence"]
102-
contracts --> validation["local validation"]
103-
104-
disabled["Disabled gates"] --> network["network"]
105-
disabled --> providers["providers"]
106-
disabled --> external["external agents"]
107-
disabled --> apply["apply"]
108-
disabled --> subexec["subagent execution"]
109-
disabled --> mcp["MCP server"]
110-
disabled --> hooks["hooks"]
111-
disabled --> plugins["plugins"]
112-
disabled --> shell["arbitrary shell"]
74+
```powershell
75+
cargo run --bin ctxt -- --json self report
76+
cargo run --bin ctxt -- --json startup readiness
77+
cargo run --bin ctxt -- --json startup flow
78+
cargo run --bin ctxt -- --json review workflow
11379
```
11480

115-
Disabled gates are explicit by design. Contract output and artifacts are evidence, not proof that an unsafe action is allowed.
116-
117-
## Quickstart
81+
### Planned Release Workflow
11882

119-
Clone the repository and run the local validation sequence from PowerShell:
83+
The crate install path is planned for the tagged release. Until the crate is published, use the source workflow above.
12084

12185
```powershell
122-
git clone https://github.com/ProfRandom92/comptext-cli.git
123-
cd comptext-cli
124-
cargo fmt --all --check
125-
cargo check
126-
cargo test
127-
cargo clippy -- -D warnings
86+
cargo install comptext-cli --locked
87+
ctxt --json capabilities
12888
```
12989

130-
Inspect the local runtime contracts:
90+
## Using With Codex / Antigravity
91+
92+
`ctxt` gives Codex, Antigravity, and human reviewers a shared local contract surface. It is an adapter-friendly runtime boundary, not a remote orchestration layer.
93+
94+
Before edits:
13195

13296
```powershell
133-
cargo run --bin ctxt -- --json self report
13497
cargo run --bin ctxt -- --json startup readiness
135-
cargo run --bin ctxt -- --json startup flow
98+
cargo run --bin ctxt -- --json capabilities
13699
cargo run --bin ctxt -- --json review workflow
100+
```
101+
102+
After edits:
103+
104+
```powershell
137105
cargo run --bin ctxt -- --json validate --run
138106
```
139107

140-
All commands are local CLI invocations. The documented review workflow does not enable network access, provider calls, external agent execution, proposal application, review application, or subagent execution.
108+
The commands above are local CLI invocations. They do not enable provider calls, network access, external agent execution, proposal application, review application, or subagent runtime execution.
141109

142110
## Command Matrix
143111

144-
| Command | Purpose | Output style | Safety posture |
145-
|---|---|---|---|
146-
| `cargo run --bin ctxt -- --json self report` | Local runtime baseline and safe entrypoints | JSON | Read-only contract |
147-
| `cargo run --bin ctxt -- --json schema` | Supported JSON command shapes | JSON | Static contract |
112+
| Command | Purpose | Output | Boundary |
113+
|---|---|---:|---|
114+
| `cargo run --bin ctxt -- --json self report` | Runtime baseline and safe entrypoints | JSON | Read-only contract |
115+
| `cargo run --bin ctxt -- --json schema` | Stable command-shape discovery | JSON | Static contract |
148116
| `cargo run --bin ctxt -- --json capabilities` | Supported features and disabled gates | JSON | Read-only contract |
149-
| `cargo run --bin ctxt -- --json startup readiness` | Startup readiness status | JSON | Contract-only report |
150-
| `cargo run --bin ctxt -- --json startup flow` | Safe startup sequence | JSON | Contract-only checklist |
151-
| `cargo run --bin ctxt -- --json review workflow` | Deterministic review workflow plan | JSON | Contract-only checklist |
152-
| `cargo run --bin ctxt -- --json subagents list` | Deterministic subagent role contracts | JSON | Lists roles only |
117+
| `cargo run --bin ctxt -- --json startup readiness` | Startup readiness report | JSON | Contract-only |
118+
| `cargo run --bin ctxt -- --json startup flow` | Safe startup sequence | JSON | Contract-only |
119+
| `cargo run --bin ctxt -- --json review workflow` | Deterministic review workflow plan | JSON | Contract-only |
120+
| `cargo run --bin ctxt -- --json subagents list` | Subagent role contracts | JSON | Role definitions only |
153121
| `cargo run --bin ctxt -- --json proposals list` | Local proposal artifact index | JSON | Read-only evidence |
154-
| `cargo run --bin ctxt -- --json proposals inspect latest --max-bytes 12000` | Bounded latest proposal read | JSON | Read-only evidence |
155-
| `cargo run --bin ctxt -- --json proposals validate latest` | Validate proposal artifact contract | JSON | Validation only |
122+
| `cargo run --bin ctxt -- --json proposals inspect latest --max-bytes 12000` | Bounded proposal read | JSON | Read-only evidence |
123+
| `cargo run --bin ctxt -- --json proposals validate latest` | Proposal artifact contract check | JSON | Validation only |
156124
| `cargo run --bin ctxt -- --json reviews list` | Local review artifact index | JSON | Read-only evidence |
157-
| `cargo run --bin ctxt -- --json reviews inspect latest --max-bytes 12000` | Bounded latest review read | JSON | Read-only evidence |
158-
| `cargo run --bin ctxt -- --json reviews validate latest` | Validate review artifact contract | JSON | Validation only |
125+
| `cargo run --bin ctxt -- --json reviews inspect latest --max-bytes 12000` | Bounded review read | JSON | Read-only evidence |
126+
| `cargo run --bin ctxt -- --json reviews validate latest` | Review artifact contract check | JSON | Validation only |
159127
| `cargo run --bin ctxt -- --json agent discover` | Local agent discovery metadata | JSON | Discovery only |
160128
| `cargo run --bin ctxt -- --json runs list` | Local run artifact index | JSON | Read-only evidence |
161-
| `cargo run --bin ctxt -- --json runs read latest --max-bytes 12000` | Bounded latest run read | JSON | Read-only evidence |
129+
| `cargo run --bin ctxt -- --json runs read latest --max-bytes 12000` | Bounded run artifact read | JSON | Read-only evidence |
162130
| `cargo run --bin ctxt -- --json validate --run` | Local validation contract execution | JSON | Local validation |
163131

164132
## Capability Matrix
165133

166134
| Capability | v0.1.0 RC status | Notes |
167135
|---|---:|---|
168136
| Runtime self-reporting | Available | Local JSON contract |
169-
| Schema introspection | Available | Stable command-shape discovery |
137+
| Schema introspection | Available | Stable output-shape discovery |
170138
| Capabilities introspection | Available | Reports supported features and disabled gates |
171139
| Startup readiness | Available | Contract-only readiness report |
172140
| Startup flow | Available | Contract-only startup checklist |
@@ -178,29 +146,66 @@ All commands are local CLI invocations. The documented review workflow does not
178146
| Review artifact inspection | Available | Bounded reads with max-byte limits |
179147
| Review artifact validation | Available | Contract validation only |
180148
| Subagent role contracts | Available | Deterministic role definitions only |
181-
| Local agent discovery | Available | Discovery metadata only |
149+
| Local agent discovery | Available | Metadata discovery only |
182150
| Run artifact inspection | Available | Local evidence inspection |
183151
| Local validation | Available | `validate --run` contract |
184-
| MCP server | Not implemented | Badge and matrix state this explicitly |
185-
| Provider execution | Disabled | No live provider call is part of this README workflow |
186-
| External agent execution | Disabled | Discovery and contracts do not execute agents |
187-
| Proposal or review application | Disabled | Application is outside this release-candidate README workflow |
188-
| Subagent runtime execution | Disabled | Role contracts are not execution |
152+
| Binary/media context-pack exclusion | Available | README assets do not break context packing |
153+
| MCP server | Not implemented | No server availability claim |
154+
| Provider gateway | Not implemented | No live provider gateway claim |
155+
| External agent execution | Disabled | Contracts and discovery do not execute agents |
156+
| Proposal or review application | Disabled | Artifacts are not auto-applied |
157+
| Subagent runtime execution | Disabled | Role contracts are not runtime execution |
158+
159+
## Architecture
160+
161+
```mermaid
162+
flowchart LR
163+
human["Human reviewer"] --> cli["ctxt CLI"]
164+
codex["Codex"] --> cli
165+
antigravity["Antigravity"] --> cli
166+
cli --> contracts["Agent-readable JSON contracts"]
167+
contracts --> startup["Startup and capability state"]
168+
contracts --> evidence["Local artifacts and bounded reads"]
169+
contracts --> validation["Validation output"]
170+
startup --> summary["User summary"]
171+
evidence --> summary
172+
validation --> summary
173+
```
174+
175+
`ctxt` keeps the first interaction local and deterministic. Callers ask the runtime what is supported, what is disabled, what evidence exists, and what validation says.
176+
177+
## Review Workflow
178+
179+
```mermaid
180+
flowchart TD
181+
readiness["startup readiness"] --> flow["startup flow"]
182+
flow --> schema["schema"]
183+
schema --> capabilities["capabilities"]
184+
capabilities --> subagents["subagent role contracts"]
185+
subagents --> proposals["proposal artifacts"]
186+
proposals --> reviews["review artifacts"]
187+
reviews --> workflow["review workflow"]
188+
workflow --> validate["validate --run"]
189+
validate --> summary["user summary"]
190+
```
191+
192+
The review workflow is a checklist contract. It does not run hidden automation, invoke external agents, call providers, apply artifacts, or change Git state.
189193

190194
## Safety Matrix
191195

192-
| Boundary | Default | Rationale |
196+
| Boundary | Default | README R2 wording |
193197
|---|---|---|
194-
| Network | Denied | Local evidence and deterministic contracts come first |
195-
| Provider calls | Denied | Providers are not needed for contract inspection |
196-
| External agents | Denied | Discovery is metadata, not execution |
197-
| Proposal apply | Denied | Proposal artifacts are untrusted evidence |
198-
| Review apply | Denied | Review artifacts are untrusted evidence |
199-
| Subagent execution | Denied | Listed subagents are role contracts only |
200-
| MCP server | Not implemented | No README claim should imply MCP availability |
201-
| Hooks and plugins | Disabled for this flow | Not required for v0.1.0 contract-runtime validation |
202-
| Arbitrary shell | Out of scope | Use declared validation commands only |
203-
| Secrets | Never read or printed | Secret material must not enter reports, logs, artifacts, or context packs |
198+
| Network | Denied | Local-first workflow; no network by default |
199+
| Provider calls | Disabled | Providers are not called by documented contract inspection |
200+
| External agents | Disabled | Discovery metadata is not execution |
201+
| Proposal apply | Disabled | Proposal artifacts are untrusted evidence |
202+
| Review apply | Disabled | Review artifacts are untrusted evidence |
203+
| Subagent runtime execution | Disabled | Subagent role contracts are available only as definitions |
204+
| MCP server | Not implemented | No MCP server implementation claim |
205+
| Provider gateway | Not implemented | No provider gateway claim |
206+
| Hooks and plugins | Disabled for this flow | Not required for release-candidate validation |
207+
| Arbitrary shell | Out of scope | Use declared local validation commands |
208+
| Secrets | Never read or printed | Secret material must not enter artifacts or reports |
204209
| Git writes | User-authorized only | Commit, push, tag, and release require explicit instruction |
205210

206211
## Validation Evidence
@@ -217,7 +222,7 @@ unit tests: 38 green
217222
smoke tests: 83 green
218223
```
219224

220-
Recommended local validation before reporting success:
225+
Recommended local validation:
221226

222227
```powershell
223228
cargo fmt --all --check
@@ -227,47 +232,63 @@ cargo clippy -- -D warnings
227232
cargo run --bin ctxt -- --json validate --run
228233
```
229234

230-
## Visual Asset Plan
235+
For README-only edits, the minimum documentation check is:
231236

232-
README diagrams stay as Mermaid so they remain version-controlled, reviewable, and rendered directly by GitHub.
237+
```powershell
238+
git --no-pager diff -- README.md
239+
git --no-pager status --short --branch
240+
```
233241

234-
Figma can be used later for a GitHub README header, social preview card, footer strip, architecture poster, and launch image. Generated asset references should not be added unless matching files already exist in the repository and the active task explicitly allows them.
242+
## Distribution / Release Channel
235243

236-
## Roadmap
244+
v0.1.0 is currently a release candidate. The source workflow is the supported path until the release is tagged and the crate publication decision is made.
245+
246+
Release actions that remain separate from this README:
237247

238-
The active project source of truth is `PROJEKT.md`, and concrete work slices live in `tasks/*.md`.
248+
- tag creation,
249+
- GitHub Release creation,
250+
- crate publication,
251+
- cargo-dist initialization,
252+
- social preview setup.
253+
254+
Do not infer that any of those actions have happened from this README.
255+
256+
## Roadmap
239257

240258
Near-term release-candidate priorities:
241259

242-
- keep README and task state aligned with Phase 5e,
260+
- keep README, release notes, and project state aligned,
243261
- preserve deterministic JSON contract behavior,
244262
- keep local validation green,
245-
- improve community-facing examples without widening runtime permissions,
246-
- add visual assets only in a dedicated visual-assets task.
263+
- document Codex and Antigravity usage through `ctxt`,
264+
- keep binary and media assets outside context packing,
265+
- decide release tag and distribution channel only after CI is green.
266+
267+
Later work may expand installation paths, packaging, and visual launch assets without changing the core local-first boundary.
247268

248269
## Contributing
249270

250-
Contributions should preserve the core safety model:
271+
Contributions should preserve the project contract:
251272

252-
- deterministic contracts before provider interaction,
273+
- deterministic Context Packs before provider interaction,
253274
- dry-run before network,
254275
- proposal before apply,
255276
- model, provider, and tool output treated as untrusted input,
256277
- local validation before success claims,
257278
- no secrets in stdout, stderr, reports, context packs, proposals, snapshots, logs, or generated artifacts.
258279

259-
For README/community work, stay inside the declared task scope and validate with:
280+
Use the same startup checks before changing behavior:
260281

261282
```powershell
262-
git --no-pager diff -- README.md
263-
git --no-pager status --short --branch
283+
cargo run --bin ctxt -- --json startup readiness
284+
cargo run --bin ctxt -- --json capabilities
285+
cargo run --bin ctxt -- --json review workflow
264286
```
265287

266288
## License
267289

268290
MIT.
291+
269292
<p align="center">
270-
<img src="assets/brand/comptext-cli-readme-footer.jpg" alt="CompText CLI — Compress the noise. Preserve the proof." width="100%">
293+
<img src="assets/brand/comptext-cli-readme-footer.jpg" alt="CompText CLI - Compress the noise. Preserve the proof." width="100%">
271294
</p>
272-
273-

0 commit comments

Comments
 (0)