README.md

Moltark Docs

This directory documents the current Moltark architecture and the intended direction of travel.

The docs are arranged for incremental discovery:

1. Start with Core Concepts.
2. Then read Modules And Providers.
3. Then read Execution Model.
4. If you are changing tests or adding behavior, read Testing.
5. If you are evaluating architecture decisions, read Future Paths.
6. If you need prior-art and external comparisons, read Research Notes.

Current Scope

The current MVP implementation is intentionally narrow:

• one root molt.star per repository
• Python projects as the first concrete project type
• astral/uv as the first concrete provider module
• reconciliation of pyproject.toml, .gitattributes, and .moltark/state.json
• Bazel/Gazelle as the developer build and test loop for this repository
• local Bazel rules for first-class Gherkin feature inputs used by godog

The architecture is being shaped for broader module and capability composition, but the implementation is still local-first-party and Python-first today.

Reading By Task

If you need to understand:

• the reconciler model: Core Concepts
• how use("...") works today: Modules And Providers
• the difference between synth hooks, bootstrap requirements, user tasks, and triggers: Execution Model
• how snapshots and Gherkin tests are organized: Testing
• how the repo is built and regenerated locally: see README.md and Testing
• what is intentionally not implemented yet: Future Paths
• what we learned from adjacent tools and internal notes: Research Notes