myArch: A Systematic Development Framework

Left-rule blocks mark artificial prose; quotations retain their own attribution.

myArch gives structure an address: indexed headings for documents, and a separate four-level cell model for architectonic Python code. You can inspect a document's numbering, preview a repair, and apply it without making every heading look alike.

Documentation: arch.docs.doering.ai

Installation

Use Python 3.14+. These examples follow the 2.1 source tree; the published 1.0 package uses an older configuration schema. Install from Git for the behavior described here (release notes):

uv tool install 'git+https://gitlab.com/doering-ai/libs/arch.git'
# Or, in an activated Python 3.14+ virtual environment:
python -m pip install 'git+https://gitlab.com/doering-ai/libs/arch.git'

Try an address

$ arch --json idx parse '1.2'
{"version": 1, "rendered": "1.2", "ordinals": [0, 1], "depth": 2, "styles": ["number", "number"]}

The visible address is one-based; its internal ordinals are zero-based. Document indexes can be numeric, alphabetic, Roman, or symbolic, with dotted or compact rendering and optional markers and wrappers. Their depth is arbitrary: changing the presentation doesn't change the place.

Inspect, then apply

From this repository's checkout, these commands inspect one configured document:

arch check docs/idx.md
arch --json plan docs/idx.md
arch format --check docs/idx.md
arch format --diff docs/idx.md

check reports index diagnostics; plan exposes the proposed edits. The two format commands check header presentation or print a patch without writing it. When you're ready, apply writes the index plan, while bare format writes the header-format plan:

arch apply docs/idx.md
arch format docs/idx.md

Each file is planned, checked against its source digest, and atomically replaced. Its newline convention and final-newline state survive the edit. This is a per-file write boundary.

Choose what participates

Seeing an index doesn't enroll a file. Index planning needs an indexing.paths rule or an explicit --spec override. Within an enrolled file, observed inserts only at hierarchy depths already represented there; all is allowed only on an explicit path rule.

Configuration precedence is command flags, an explicit --config, the nearest .arch.yaml, ~/.config/my/arch.yaml, then built-ins. Index enrollment and header formatting have independent selectors, with higher-precedence rules tried first. For example:

specs:
    formal-markdown:
        styles: [number]
        separator: '.'
        wrapper: '`'

indexing:
    default: off
    insertion: observed
    paths:
        - glob: 'policies/**'
          spec: formal-markdown
          insertion: all

header_mode: flex

header_defaults:
    markdown: markdown
    source: source
    typst: off
    rst: off
    unknown: off

header_paths:
    - path: 'README.md'
      profile: off

ignore:
    - 'vendor/**'

Header formatting defaults to flex: existing indexed shapes establish file-local level precedents, preserving authored presentation. Use header_mode: strict or arch format --mode strict when the configured profile should set case and geometry. The built-in Markdown profile keeps title case, leaves H1 unindexed, and renders recognized H2+ indexes as dotted backtick tags such as `1.2`. Typst, reStructuredText, and unknown suffixes remain off until they have structural adapters.

Use arch config show --path FILE to inspect the selected family, enrollment, spec/profile sources, insertion policy, and matching ignore rule.

Tag a multi-file work

An edition split into chapter files, with an index.md whose toctree lists them, is tagged as one outline by arch book. Every heading but a part heading gets a backtick tag such as `3.2.`, front matter takes `0.`, and titles are never edited. A part heading, the # [Commentary, part 2] that opens each later file of a section cut in parts, continues the H1 before it and takes no tag. A work is touched only when --spec names a backtick spec (the built-in lit is one) or an indexing.paths rule enrolls its index.md:

arch book check --spec lit works/demo
arch book plan --spec lit works/demo
arch book apply --spec lit works/demo
arch book outline --spec lit works/demo

plan and apply print the old-to-new renumber map for tags that shift when a heading is inserted or removed. arch.idx.read_outline() gives other tools each heading's idx, file, line, level, and title straight from the tags, with no sidecar file.

Two index domains

arch.idx.Idx is the non-empty, arbitrary-depth document address used above. arch.Quad is the original fixed, four-place architectonic address; arch.Idx remains its compatibility name. A Quad admits the empty root and abstract a / b halves, with a special four-branch ancestry. These domains are separate, not subtypes of one another.

The Python library adds Lang and Cell, the Architectonic registry and default ARCH instance, and source-code models including Module, File, and Element. The thesis, antithesis, and synthesis decorators alias an element's three moments onto its class. The package guide points to these entry points.

Terminal workspace

With the optional terminal extra installed, bare arch opens the PyRatatui browser when stdin and stdout are terminals. For captured output or scripts, use a subcommand. arch spec --input headers.yaml --output headers.yaml opens the profile editor for an existing specification and can save changes to that file. See the header formatting guide for the editor and HeaderSpec.

Further reading

• Document index guide
• Tagging a work across chapter files
• Index design
• Document index API
• Header formatting