Skip to content

Commit 52b0fe3

Browse files
hyperpolymathclaude
andcommitted
docs(readme): convert README.adoc -> Markdown README.md
README must be real Markdown to render in GitHub community-health, the GitHub profile, and external MCP directories (Glama) — AsciiDoc shows as raw markup there. pandoc asciidoc->GFM, badges fixed to clickable, SPDX header kept as an HTML comment, duplicate README.adoc removed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
1 parent 6a196ad commit 52b0fe3

2 files changed

Lines changed: 106 additions & 100 deletions

File tree

README.adoc

Lines changed: 0 additions & 100 deletions
This file was deleted.

README.md

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
<!--
2+
SPDX-License-Identifier: CC-BY-SA-4.0
3+
SPDX-FileCopyrightText: 2025-2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
4+
-->
5+
6+
# Internet Society Transactor
7+
8+
Check, fix, and submit documents across all Internet Society streams:
9+
IETF, IRTF, IAB, Independent Stream, IANA, and RFC Editor.
10+
11+
## Features
12+
13+
- **Multi-stream support** — Not just IETF. Handles IRTF Research
14+
Groups, IAB documents, Independent Stream submissions, IANA registry
15+
requests, and RFC Editor workflows.
16+
17+
- **Parse RFC XML v3 and plain text** — Full RFC 7991 XML parser plus
18+
winnow-based plain-text parser.
19+
20+
- **Smart fix classification** — Every fix is classified as AutoSafe
21+
(zero risk), Recommended (review advised), or ManualOnly (human
22+
required).
23+
24+
- **Nickel-powered templates** — Type-checked contracts, per-stream
25+
templates, and policy validation via Nickel.
26+
27+
- **State machine tracking** — Full lifecycle tracking with per-stream
28+
state machines (IETF: 20+ states, IRTF: 8, IAB: 4, etc.).
29+
30+
- **Desktop GUI** — Gossamer + ReScript TEA architecture with document
31+
editor, checker, and fixer views.
32+
33+
- **Pure Rust dependencies** — gix (not git2-rs), reqwest with rustls
34+
(not openssl).
35+
36+
## Quick Start
37+
38+
```bash
39+
# Check a document
40+
cargo run -p intsoc-cli -- check path/to/draft.xml
41+
42+
# Fix auto-safe issues
43+
cargo run -p intsoc-cli -- fix --auto-only path/to/draft.xml
44+
45+
# Preview all fixes (dry run)
46+
cargo run -p intsoc-cli -- fix --dry-run path/to/draft.xml
47+
48+
# Check submission status
49+
cargo run -p intsoc-cli -- status draft-jewell-http-430-consent-required-00
50+
51+
# Initialize a new draft
52+
cargo run -p intsoc-cli -- init draft-jewell-new-feature-00 --stream individual
53+
```
54+
55+
## Architecture
56+
57+
crates/
58+
intsoc-core/ # Domain model, state machines, validation framework
59+
intsoc-parser/ # RFC XML v3, plain-text, idnits output parsing
60+
intsoc-fixer/ # Fix engine (AutoSafe/Recommended/ManualOnly)
61+
intsoc-nickel/ # Nickel template rendering + policy validation
62+
intsoc-git/ # Git integration via gix
63+
intsoc-api/ # IETF Datatracker + IANA API clients
64+
intsoc-cli/ # CLI binary (intsoc check/fix/submit/status/init)
65+
gui/
66+
src/ # ReScript TEA frontend
67+
backend/ # Gossamer desktop backend (Rust)
68+
gossamer.conf.json # Gossamer window/app configuration
69+
nickel/
70+
contracts/ # Type contracts for metadata validation
71+
templates/ # Per-stream document templates
72+
policies/ # Submission rules per organization
73+
haskell/ # Megaparsec parser helpers (Phase 2)
74+
src/abi/ # Idris2 ABI definitions (Phase 3)
75+
ffi/zig/ # Zig FFI implementation (Phase 3)
76+
77+
## Supported Streams
78+
79+
| Organization | Streams | Key Characteristics |
80+
|----|----|----|
81+
| IETF | Individual, WG, Standards Track, Informational, Experimental, BCP, BIS | 20+ lifecycle states, idnits validation |
82+
| IRTF | Research Group, Individual | 8 states, IRSG review |
83+
| IAB | Document, Statement | 4 states, IAB review |
84+
| Independent | Submission (RFC 4846) | 5 states, ISE review |
85+
| IANA | Registry Request, Parameter Assignment | 6 states, expert review |
86+
| RFC Editor | Errata, Editorial | Editorial stream |
87+
88+
## Building
89+
90+
```bash
91+
# Build all crates
92+
cargo build --workspace
93+
94+
# Run tests
95+
cargo test --workspace
96+
97+
# Build release
98+
cargo build --workspace --release
99+
```
100+
101+
## License
102+
103+
MPL-2.0 (Palimpsest License)
104+
105+
Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath)
106+
\<[j.d.a.jewell@open.ac](j.d.a.jewell@open.ac).uk\>

0 commit comments

Comments
 (0)