Skip to content

Quick Start

This page takes you from an empty repository to a corpus that arqix scaffolds, traces, verifies, and publishes. Every command and every output block below is real: the sequence was run as-is against the current build.

Install

cargo install arqix

You need a current stable Rust toolchain; the crate installs the latest release, --git https://github.com/HenryCFnord/arqix the development state.

Scaffold a documentation package

git init my-docs && cd my-docs
arqix doc init

initialised documentation package

This creates docs/index.md, the entry point of the package. All arqix commands resolve their configuration from arqix.toml in the working directory; no file means defaults, and docs/ is the default root.

Create your first requirement

arqix doc new requirement --title "Parse frontmatter"

created REQUIREMENT-0001 at docs/requirement/REQUIREMENT-0001.md

The scaffold carries the full unit structure: identity (id, iri), typing (rdf.type), a triples list for relations, and lifecycle metadata. Now author it — write the actual obligation into the body, declare its kind, and set it active (a requirement's lifecycle vocabulary is active or retired; there is no draft requirement, because an unfinished obligation is not yet a requirement):

rdf:
  type:
    - arqix:classes/functional-requirement
meta:
  lifecycle-status: active

## Parse frontmatter

When a document is read, the parser shall expose its frontmatter as structured data.

Close the loop with a marker

Traceability in arqix does not stop at documents: a comment marker attaches a test to the requirement it proves. Create a test — any code tree works, the marker is just a comment:

// tests/parser.rs
// arqix:verifies REQUIREMENT-0001
#[test]
fn frontmatter_is_read() {
    // your actual assertion here
}

Then ask arqix for the coverage picture:

arqix trace coverage

| requirement | kind | verified by | planned by | implemented by |
| --- | --- | --- | --- | --- |
| REQUIREMENT-0001 | functional | tests/parser.rs:2 | — | — |
functional: 1 verified, 0 planned, 0 uncovered (of 1)
coverage: 0 error(s), 0 warning(s)

An arqix:implements marker in source code adds the third column the same way. Markers on #[ignore]d tests count as planned, not verified — a red skeleton is a promise, not proof.

Verify the corpus

arqix verify

ok   format (exit 0)
ok   lint (exit 0)
ok   trace-scan (exit 0)
ok   coverage (exit 0)
ok   ratchet (exit 0)
verify: ok

One command runs the configured sub-steps: formatting, structural lint, the trace-graph scan, coverage, and the coverage ratchet. Coverage is informational by default — it measures progress and never gates a change — while the ratchet gates regressions: a requirement that was verified must stay verified unless it is retired. The steps and their treatment are configuration, not convention; see the verify policy.

Publish the site

arqix stages artefact-ready pages and orchestrates a site toolchain — it never renders HTML itself. Configure the toolchain (Zensical is the recommended default) and point it at the staging directory:

# arqix.toml
[policies.publish]
site-command = "zensical build"

# zensical.toml
[project]
site_name = "my-docs"
docs_dir = "site-src"
site_dir = "site-build"

pip install zensical==0.0.50
arqix publish site

Build started
No issues found
Build finished in 0.29s
staged 2 page(s) to site-src; toolchain 'zensical build' ok

Staged pages are artefact-ready: include directives expanded, marker comments stripped, and the frontmatter reduced to what the toolchain consumes. Your rendered site is now in site-build/; add site-src/ and site-build/ to .gitignore.

Where to go next