quints 0.3.0__tar.gz → 0.4.0__tar.gz

{quints-0.3.0 → quints-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quints
-Version: 0.3.0
+Version: 0.4.0
 Summary: Swiss VAT & accounting toolkit for plain-text (beancount) books: MWST reports and quarterly settlement, Bezugsteuer helpers, BAZG daily FX rates, QR-bill invoicing, KMU statutory statements, and statement importers (UBS MT940, Wise, Stripe) that draft into a staging area
 License: GPL-2.0-only
 License-File: LICENSE
@@ -27,6 +27,8 @@ Description-Content-Type: text/markdown
 
 Swiss VAT & accounting toolkit for plain-text ([beancount](https://github.com/beancount/beancount)) books.
 
+![quints init scaffolds sample books, quints check validates them, and quints mwst prints the Form-310 VAT return](https://raw.githubusercontent.com/sealambda/quints/main/docs/assets/quickstart.gif)
+
 Everything a Swiss micro-company (GmbH, AG, or Einzelfirma) needs on top of beancount + Fava:
 
 - **MWST**: quarterly VAT report mapped to the ESTV form Ziffern, settlement

{quints-0.3.0 → quints-0.4.0}/README.md

@@ -2,6 +2,8 @@
 
 Swiss VAT & accounting toolkit for plain-text ([beancount](https://github.com/beancount/beancount)) books.
 
+![quints init scaffolds sample books, quints check validates them, and quints mwst prints the Form-310 VAT return](https://raw.githubusercontent.com/sealambda/quints/main/docs/assets/quickstart.gif)
+
 Everything a Swiss micro-company (GmbH, AG, or Einzelfirma) needs on top of beancount + Fava:
 
 - **MWST**: quarterly VAT report mapped to the ESTV form Ziffern, settlement

quints-0.4.0/examples/.gitignore

@@ -0,0 +1,8 @@
+# quints working directories. documents/ (filed sources and rendered
+# invoices) is deliberately NOT ignored — the ledger links to it.
+/staging/
+.env
+__pycache__/
+.venv/
+.DS_Store
+.wise/

quints-0.4.0/examples/AGENTS.md

@@ -0,0 +1,120 @@
+# Working on Example GmbH's books with an AI agent
+
+These are plain-text ([beancount](https://beancount.github.io)) books managed
+with [`quints`](https://github.com/sealambda/quints). **`quints` is a
+deterministic tool — you drive it, it never calls a model.** Your job is to
+extend and maintain the ledger; `quints` validates and reports on it.
+
+## Setup
+
+`uv sync` once — it installs quints, which brings beancount and fava along.
+Then `uv run quints check` (or activate the venv and call `quints` and the
+standard beancount tools directly).
+
+This project is a git repository; `quints init` committed the pristine
+scaffold. Work in reviewable steps: `git diff` before moving drafts into
+`books/`, commit once `quints check` passes — the history is the audit trail.
+
+## Layout
+
+- `main.bean` — options, plugins, includes; the entry point every tool loads.
+  `plugin "quints.plugins.kmu"` is enabled: every `*:CH:GmbH:*` account
+  **must** be opened with a four-digit `kmu:` code (Swiss KMU Kontenrahmen).
+- `accounts.bean` — the chart of accounts (all `open` directives).
+- `books/2026.bean` — transactions, one file per fiscal year. `main.bean`
+  includes `books/*.bean`, so a new year just needs a new file.
+- `commodities.bean` — currencies; `prices.bean` — FX rates, refresh with
+  `quints prices sync`.
+- `quints.toml` — entity config (name, legal form, VAT, importer rules). VAT
+  *rates* are law and live in code, not here.
+- `staging/` — importer drafts land here (git-ignored, transient).
+- `inbox/` — incoming source documents, not yet filed.
+- `documents/` — filed documents, mirroring the account tree as
+  `documents/<Account/Tree>/YYYY-MM-DD.payee.description.pdf`. Committed:
+  the ledger links to these files (`fava.plugins.link_documents`).
+- `invoicing/` — issuer identity (`issuer.yaml`), customer registry
+  (`customers.yaml`), one YAML per issued invoice.
+
+## Extending the chart of accounts (the part that needs judgement)
+
+Add income/expense sub-trees for this business as `open` directives in
+`accounts.bean`, each with the KMU code it rolls up to, e.g.:
+
+```beancount
+2026-01-01 open Expenses:CH:GmbH:Marketing:Ads CHF
+  kmu: "6600"  ; Advertising
+```
+
+See the codes already in use:
+
+```bash
+quints report konten --year 2026
+```
+
+Pick codes from the KMU Kontenrahmen; `quints check` fails on a `:CH:GmbH:`
+account with no valid `kmu:` code.
+
+## The loop — money out (statements → books)
+
+1. Draft bank/PSP activity into `staging/`. Configured importers:
+   - `quints import ubs <statement.mt940>` — the MT940 export from UBS e-banking; no credentials.
+   - `quints import wise --fetch --from <date> --to <date>` — needs `QUINTS_WISE_API_TOKEN` in `.env` (plus `QUINTS_WISE_PRIVATE_KEY` for SCA-protected profiles; the key pair lives in `.wise/`, git-ignored).
+   - `quints import stripe --fetch --from <date> --to <date>` — needs `QUINTS_STRIPE_API_KEY` in `.env` (a restricted read-only key for the `[import.stripe]` account).
+2. Review each draft in `staging/`. A draft is a flagged (`!`) transaction
+   with only the cash leg known:
+
+```beancount
+2026-07-20 ! "ACME AG" "Payment order"
+  Assets:CH:GmbH:Current:UBS:CHF  -250.00 CHF
+```
+
+   Complete the counter leg, decide the VAT treatment (InputVAT /
+   Bezugsteuer / none), link the source document, flip `!` to `*`, and move
+   it into `books/2026.bean`. `quints match` scores staging drafts and
+   inbox documents against invoices and bookings.
+3. **Always** `quints check` before you consider the books consistent.
+
+## The loop — money in (invoice → receivable → payment)
+
+1. Describe the invoice as a YAML file in `invoicing/` (each file carries a
+   `$schema` modeline, so schema-aware editors validate it as you type).
+2. `quints invoice invoicing/<file>.yaml` renders the PDF into `documents/`
+   under the income account and cross-checks the total against the ledger.
+   Not booked yet? It prints the receivable draft to paste into
+   `books/2026.bean`.
+3. The payment arrives with the next bank import; the draft is matched to
+   the open invoice by its QR/SCOR reference. `quints receivables` shows
+   what is still open.
+
+## Machine-readable surfaces (prefer these over scraping text)
+
+Every reporting command takes `--json` — stable keys, ISO dates, decimal
+strings:
+
+```bash
+quints check --json
+quints mwst -q 2026-Q3 --json
+quints status --json
+quints report bilanz --at 2026-12-31 --json
+quints receivables --json
+```
+
+JSON Schemas for the invoicing files are hosted at
+https://sealambda.github.io/quints/schema/ (`quints schema` writes them
+locally to `invoicing/schema/`).
+
+Never invent VAT numbers or rates — compute them with `quints mwst`.
+
+## Sample data — replace before the books are real
+
+The scaffold seeded a demo quarter so every command has data. Before
+booking real activity:
+
+- [ ] `invoicing/issuer.yaml` — the VAT ID (CHE-267.359.056 MWST) and both
+      IBANs are checksum-valid fakes; put the real ones in.
+- [ ] `invoicing/customers.yaml` — replace the demo customers (acme, globex).
+- [ ] `invoicing/acme-2026-07.yaml` and `invoicing/globex-2026-08.yaml`
+      — delete the demo invoices.
+- [ ] `books/2026.bean` — delete the block marked *sample activity*.
+- [ ] `prices.bean` — drop the demo EUR rates, then `quints prices sync`.
+- [ ] `quints.toml` — the placeholder IBAN under `[import.ubs]`.

quints-0.4.0/examples/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

{quints-0.3.0 → quints-0.4.0}/examples/invoicing/acme-2026-07.yaml

@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=https://sealambda.github.io/quints/schema/invoice.schema.json
 # Sample domestic invoice — a Swiss QR-bill. It ties to the ^INV2026014
 # booking in books/2026.bean (net 1'000.00 + 8.1% VAT = 1'081.00), so
 # `quints invoice` cross-checks it clean against the ledger.

{quints-0.3.0 → quints-0.4.0}/examples/invoicing/customers.yaml

@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=https://sealambda.github.io/quints/schema/customers.schema.json
 # Customer registry — invoices reference these entries by key. A customer
 # is a flat entry, or a dated `versions` history for address changes.
 acme:

{quints-0.3.0 → quints-0.4.0}/examples/invoicing/globex-2026-08.yaml

@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=https://sealambda.github.io/quints/schema/invoice.schema.json
 # Sample export invoice — foreign currency, reverse charge, no QR part.
 # Ties to the ^INV2026015 booking in books/2026.bean (500.00 EUR).
 number: INV2026015

{quints-0.3.0 → quints-0.4.0}/examples/invoicing/issuer.yaml

@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=https://sealambda.github.io/quints/schema/issuer.schema.json
 # Issuer identity for `quints invoice` — name, address, VAT ID, and one
 # bank account per invoicing currency. Sample data: replace the VAT ID
 # and IBANs with your own before issuing a real invoice.

{quints-0.3.0 → quints-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "quints"
-version = "0.3.0"
+version = "0.4.0"
 description = "Swiss VAT & accounting toolkit for plain-text (beancount) books: MWST reports and quarterly settlement, Bezugsteuer helpers, BAZG daily FX rates, QR-bill invoicing, KMU statutory statements, and statement importers (UBS MT940, Wise, Stripe) that draft into a staging area"
 readme = "README.md"
 requires-python = ">=3.10"

quints-0.4.0/src/quints/__init__.py

@@ -0,0 +1,7 @@
+"""quints — Swiss VAT & accounting for plain-text (beancount) books."""
+
+from importlib.metadata import version
+
+# Derived from the installed distribution (pyproject.toml is the single
+# source) — a hardcoded string here drifted from the released version once.
+__version__ = version("quints")

{quints-0.3.0 → quints-0.4.0}/src/quints/cli.py

@@ -57,11 +57,26 @@ app = typer.Typer(
 )
 
 
+def _print_version(value: bool) -> None:
+    if value:
+        from . import __version__
+
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
 @app.callback()
 def _main(
     config: Path | None = typer.Option(
         None, "--config", help="quints.toml path (default: ./quints.toml, else built-in defaults)."
     ),
+    version: bool = typer.Option(
+        False,
+        "--version",
+        help="Print the quints version and exit.",
+        callback=_print_version,
+        is_eager=True,
+    ),
 ):
     config_mod.set_path(config)
 
@@ -702,7 +717,10 @@ def check(
 def invoice(
     data: Path = typer.Argument(..., help="Invoice file (.yaml/.toml/.json)."),
     out: Path | None = typer.Option(
-        None, "--out", "-o", help="Output PDF (default: <number>.pdf)."
+        None,
+        "--out",
+        "-o",
+        help="Output PDF (default: filed under documents/<income account>/).",
     ),
     issuer: Path = typer.Option(
         Path("invoicing/issuer.yaml"), "--issuer", help="Issuer config (.yaml/.toml/.json)."
@@ -734,7 +752,12 @@ def invoice(
     registry = m.load_customers(customers) if customers.exists() else None
     inv = m.load_invoice(data, registry)
     iss = m.load_issuer(issuer)
-    out = out or Path(f"{inv.number}.pdf")
+    if out is None:
+        # File the PDF the way beancount documents are filed: under the income
+        # account's folder, date-prefixed, next to the ledger's other evidence.
+        cfg = config_mod.get()
+        account = cfg.income_export if inv.kind == "export" else cfg.income_domestic
+        out = m.document_path(inv, account)
     path, totals, payload = r.render(inv, iss, out)
 
     qr_ok = None
@@ -808,7 +831,9 @@ def schema(
     """Write JSON Schemas for the invoice, issuer, and customers files.
 
     Point an editor at them (yaml-language-server modeline) for completion
-    and validation; any future UI can consume the same contract."""
+    and validation; any future UI can consume the same contract. The same
+    schemas are published on the docs site, so scaffolded YAMLs reference
+    them without running this command."""
     import json as _json
 
     from .invoice import model as m
@@ -822,6 +847,7 @@ def schema(
         path = out / f"{name}.schema.json"
         path.write_text(_json.dumps(mdl.model_json_schema(), indent=2) + "\n")
         ui.console.print(f"[ok]Wrote[/] {path}")
+    ui.console.print(f"[muted]Also hosted at {config_mod.DOCS_URL}/schema/[/]")
 
 
 @app.command()
@@ -845,6 +871,11 @@ def init(
     answers_file: Path | None = typer.Option(
         None, "--answers", help="TOML answer-file for non-interactive scaffolding."
     ),
+    use_git: bool = typer.Option(
+        True,
+        "--git/--no-git",
+        help="git init + commit the pristine scaffold (skipped inside an existing repo).",
+    ),
     force: bool = typer.Option(False, "--force", help="Overwrite existing files."),
     yes: bool = typer.Option(False, "--yes", "-y", help="Skip prompts; accept defaults."),
     as_json: bool = typer.Option(False, "--json", help="Machine-readable output."),
@@ -908,14 +939,18 @@ def init(
         typer.secho(f"ERROR: {e}", fg="red", err=True)
         raise typer.Exit(1) from None
     result = init_mod.write(directory, files, force=force)
+    git_result = init_mod.init_git(directory) if use_git and result.written else None
 
     if as_json:
+        import dataclasses
+
         _json_out(
             {
                 "directory": str(directory),
                 "entity": answers.entity_name,
                 "written": [str(p) for p in result.written],
                 "skipped": [str(p) for p in result.skipped],
+                "git": dataclasses.asdict(git_result) if git_result else None,
             }
         )
         return
@@ -923,6 +958,11 @@ def init(
         ui.console.print(f"[ok]created[/] {path}")
     for path in result.skipped:
         ui.console.print(f"[warn]exists, skipped[/] {path} (use --force to overwrite)")
+    if git_result:
+        if git_result.committed:
+            ui.console.print("[ok]git[/] initialised repository, committed the scaffold")
+        else:
+            ui.console.print(f"[warn]git[/] {git_result.detail}")
     if result.written and not result.skipped:
         ui.console.print(
             f"\nScaffolded [b]{answers.entity_name}[/] in {directory}. "

{quints-0.3.0 → quints-0.4.0}/src/quints/config.py

@@ -28,6 +28,11 @@ else:  # pragma: no cover
 
 DEFAULT_PATH = Path("quints.toml")
 
+# The published documentation site. The invoice/issuer/customers JSON Schemas
+# are hosted under <DOCS_URL>/schema/ (regenerated by `make docs`, sync-tested
+# in CI); `quints init` writes yaml-language-server modelines pointing there.
+DOCS_URL = "https://sealambda.github.io/quints"
+
 # Legal form → account-name component (Assets:CH:<component>:…). The keys are
 # the entity families the official KMU Kontenrahmen (veb.ch) prints Klasse-28
 # variants for: juristische Personen (gmbh, ag) and Einzelunternehmen;

{quints-0.3.0 → quints-0.4.0}/src/quints/init.py

@@ -416,9 +416,17 @@ _SAMPLE_IBAN = "CH93 0076 2011 6238 5295 7"
 _SAMPLE_CUSTOMER_VAT_ID = "IE1234567T"
 
 
+def _modeline(schema: str) -> str:
+    """A yaml-language-server modeline pointing at the hosted JSON Schema, so
+    editors and agents get field-level validation without running `quints
+    schema` first. The schemas are published by the docs build."""
+    return f"# yaml-language-server: $schema={config.DOCS_URL}/schema/{schema}.schema.json"
+
+
 def _issuer_yaml(answers: Answers) -> str:
     return "\n".join(
         [
+            _modeline("issuer"),
             "# Issuer identity for `quints invoice` — name, address, VAT ID, and one",
             "# bank account per invoicing currency. Sample data: replace the VAT ID",
             "# and IBANs with your own before issuing a real invoice.",
@@ -443,6 +451,7 @@ def _issuer_yaml(answers: Answers) -> str:
 def _customers_yaml(_answers: Answers) -> str:
     return "\n".join(
         [
+            _modeline("customers"),
             "# Customer registry — invoices reference these entries by key. A customer",
             "# is a flat entry, or a dated `versions` history for address changes.",
             "acme:",
@@ -467,6 +476,7 @@ def _invoice_acme_yaml(answers: Answers) -> str:
     year = _open_date(answers).year
     return "\n".join(
         [
+            _modeline("invoice"),
             f"# Sample domestic invoice — a Swiss QR-bill. It ties to the ^INV{year}014",
             f"# booking in books/{year}.bean (net 1'000.00 + 8.1% VAT = 1'081.00), so",
             "# `quints invoice` cross-checks it clean against the ledger.",
@@ -491,6 +501,7 @@ def _invoice_globex_yaml(answers: Answers) -> str:
     year = _open_date(answers).year
     return "\n".join(
         [
+            _modeline("invoice"),
             "# Sample export invoice — foreign currency, reverse charge, no QR part.",
             f"# Ties to the ^INV{year}015 booking in books/{year}.bean (500.00 EUR).",
             f"number: INV{year}015",
@@ -643,10 +654,67 @@ def _import_section(importer: str, answers: Answers) -> str:
 
 # ── AGENTS.md — the AI-first payload ─────────────────────────────────────────
 
+# Per-importer usage lines for AGENTS.md — command first, credentials after,
+# so an agent can run the roster without probing quints.toml or .env.
+_IMPORTER_USAGE = {
+    "ubs": (
+        "`quints import ubs <statement.mt940>` — the MT940 export from UBS "
+        "e-banking; no credentials."
+    ),
+    "wise": (
+        "`quints import wise --fetch --from <date> --to <date>` — needs "
+        "`QUINTS_WISE_API_TOKEN` in `.env` (plus `QUINTS_WISE_PRIVATE_KEY` for "
+        "SCA-protected profiles; the key pair lives in `.wise/`, git-ignored)."
+    ),
+    "stripe": (
+        "`quints import stripe --fetch --from <date> --to <date>` — needs "
+        "`QUINTS_STRIPE_API_KEY` in `.env` (a restricted read-only key for the "
+        "`[import.stripe]` account)."
+    ),
+}
+
+
+def _agents_import_step(answers: Answers) -> str:
+    if not answers.importers:
+        return (
+            "1. Draft bank/PSP activity into `staging/` with `quints import`. No\n"
+            "   importer is configured yet — add an `[import.<name>]` section to\n"
+            "   `quints.toml` (supported: ubs, wise, stripe)."
+        )
+    lines = ["1. Draft bank/PSP activity into `staging/`. Configured importers:"]
+    lines += [f"   - {_IMPORTER_USAGE[name]}" for name in answers.importers]
+    return "\n".join(lines)
+
+
+def _agents_sample_section(answers: Answers) -> str:
+    if not answers.include_samples:
+        return ""
+    year = _open_date(answers).year
+    lines = [
+        "",
+        "## Sample data — replace before the books are real",
+        "",
+        "The scaffold seeded a demo quarter so every command has data. Before",
+        "booking real activity:",
+        "",
+        f"- [ ] `invoicing/issuer.yaml` — the VAT ID ({_SAMPLE_VAT_ID}) and both",
+        "      IBANs are checksum-valid fakes; put the real ones in.",
+        "- [ ] `invoicing/customers.yaml` — replace the demo customers (acme, globex).",
+        f"- [ ] `invoicing/acme-{year}-07.yaml` and `invoicing/globex-{year}-08.yaml`",
+        "      — delete the demo invoices.",
+        f"- [ ] `books/{year}.bean` — delete the block marked *sample activity*.",
+        "- [ ] `prices.bean` — drop the demo EUR rates, then `quints prices sync`.",
+    ]
+    if "ubs" in answers.importers:
+        lines.append("- [ ] `quints.toml` — the placeholder IBAN under `[import.ubs]`.")
+    return "\n".join(lines) + "\n"
+
 
 def _agents_md(answers: Answers) -> str:
-    marker = _cfg(answers).entity_marker
+    cfg = _cfg(answers)
+    marker = cfg.entity_marker
     year = _open_date(answers).year
+    bank = _sub(_PRIMARY_BANK, _component(answers))
     return f"""# Working on {answers.entity_name}'s books with an AI agent
 
 These are plain-text ([beancount](https://beancount.github.io)) books managed
@@ -660,6 +728,10 @@ extend and maintain the ledger; `quints` validates and reports on it.
 Then `uv run quints check` (or activate the venv and call `quints` and the
 standard beancount tools directly).
 
+This project is a git repository; `quints init` committed the pristine
+scaffold. Work in reviewable steps: `git diff` before moving drafts into
+`books/`, commit once `quints check` passes — the history is the audit trail.
+
 ## Layout
 
 - `main.bean` — options, plugins, includes; the entry point every tool loads.
@@ -672,8 +744,13 @@ standard beancount tools directly).
   `quints prices sync`.
 - `quints.toml` — entity config (name, legal form, VAT, importer rules). VAT
   *rates* are law and live in code, not here.
-- `staging/` — importer drafts land here; `inbox/` — incoming source
-  documents; `documents/` — filed documents, mirroring the account tree.
+- `staging/` — importer drafts land here (git-ignored, transient).
+- `inbox/` — incoming source documents, not yet filed.
+- `documents/` — filed documents, mirroring the account tree as
+  `documents/<Account/Tree>/YYYY-MM-DD.payee.description.pdf`. Committed:
+  the ledger links to these files (`fava.plugins.link_documents`).
+- `invoicing/` — issuer identity (`issuer.yaml`), customer registry
+  (`customers.yaml`), one YAML per issued invoice.
 
 ## Extending the chart of accounts (the part that needs judgement)
 
@@ -685,35 +762,79 @@ Add income/expense sub-trees for this business as `open` directives in
   kmu: "6600"  ; Advertising
 ```
 
-Run `quints report konten` to see the codes already in use. Pick codes from the
-KMU Kontenrahmen; `quints check` fails on a `{marker}` account with no valid
-`kmu:` code.
+See the codes already in use:
+
+```bash
+quints report konten --year {year}
+```
+
+Pick codes from the KMU Kontenrahmen; `quints check` fails on a `{marker}`
+account with no valid `kmu:` code.
+
+## The loop — money out (statements → books)
 
-## The loop
+{_agents_import_step(answers)}
+2. Review each draft in `staging/`. A draft is a flagged (`!`) transaction
+   with only the cash leg known:
 
-1. Draft bank/PSP activity: `quints import ubs <file>` → `staging/`.
-2. Review, add the VAT decision (InputVAT / Bezugsteuer / none) and a linked
-   document, then move drafts into `books/{year}.bean`.
+```beancount
+{year}-07-20 ! "ACME AG" "Payment order"
+  {bank}  -250.00 CHF
+```
+
+   Complete the counter leg, decide the VAT treatment (InputVAT /
+   Bezugsteuer / none), link the source document, flip `!` to `*`, and move
+   it into `books/{year}.bean`. `quints match` scores staging drafts and
+   inbox documents against invoices and bookings.
 3. **Always** `quints check` before you consider the books consistent.
 
+## The loop — money in (invoice → receivable → payment)
+
+1. Describe the invoice as a YAML file in `invoicing/` (each file carries a
+   `$schema` modeline, so schema-aware editors validate it as you type).
+2. `quints invoice invoicing/<file>.yaml` renders the PDF into `documents/`
+   under the income account and cross-checks the total against the ledger.
+   Not booked yet? It prints the receivable draft to paste into
+   `books/{year}.bean`.
+3. The payment arrives with the next bank import; the draft is matched to
+   the open invoice by its QR/SCOR reference. `quints receivables` shows
+   what is still open.
+
 ## Machine-readable surfaces (prefer these over scraping text)
 
-- Every reporting command takes `--json`: `quints mwst -q 2026-Q3 --json`,
-  `quints status --json`, `quints report bilanz --json`.
-- `quints schema` writes JSON Schemas for the invoice/issuer/customer files.
+Every reporting command takes `--json` — stable keys, ISO dates, decimal
+strings:
+
+```bash
+quints check --json
+quints mwst -q {year}-Q3 --json
+quints status --json
+quints report bilanz --at {year}-12-31 --json
+quints receivables --json
+```
+
+JSON Schemas for the invoicing files are hosted at
+{config.DOCS_URL}/schema/ (`quints schema` writes them
+locally to `invoicing/schema/`).
 
 Never invent VAT numbers or rates — compute them with `quints mwst`.
-"""
+{_agents_sample_section(answers)}"""
+
+
+def _claude_md() -> str:
+    # Claude Code auto-loads CLAUDE.md; the @-include pulls AGENTS.md into
+    # context so the instructions work without the agent going looking.
+    return "@AGENTS.md\n"
 
 
 def _gitignore() -> str:
     return "\n".join(
         [
-            "# quints working directories",
+            "# quints working directories. documents/ (filed sources and rendered",
+            "# invoices) is deliberately NOT ignored — the ledger links to it.",
             "/staging/",
             ".env",
             "__pycache__/",
-            "*.pdf",  # rendered invoices/statements — regenerate from source
             ".venv/",
             ".DS_Store",
             ".wise/",  # Wise SCA signing keys
@@ -749,6 +870,7 @@ def plan(answers: Answers) -> list[ScaffoldFile]:
         ScaffoldFile(Path(f"books/{year}.bean"), _books_bean(answers)),
         *invoicing,
         ScaffoldFile(Path("AGENTS.md"), _agents_md(answers)),
+        ScaffoldFile(Path("CLAUDE.md"), _claude_md()),
         ScaffoldFile(Path(".gitignore"), _gitignore()),
         ScaffoldFile(Path("inbox/.gitkeep"), ""),
         ScaffoldFile(Path("staging/.gitkeep"), ""),
@@ -793,3 +915,48 @@ def write(target: Path, files: list[ScaffoldFile], *, force: bool = False) -> Wr
         dest.write_text(f.content)
         result.written.append(dest)
     return result
+
+
+@dataclass(frozen=True)
+class GitResult:
+    initialized: bool  # a fresh repository was created
+    committed: bool  # the pristine scaffold is the initial commit
+    detail: str = ""  # why a step was skipped or failed, for the caller to show
+
+
+def init_git(target: Path) -> GitResult:
+    """``git init`` + an initial commit of the pristine scaffold.
+
+    The repository is what makes agent edits reviewable — diff before drafts
+    move into ``books/``, revert when a change was wrong — and the initial
+    commit makes "what did the agent change" answerable from day one. A
+    ``target`` already inside a work tree (e.g. scaffolding a subdirectory of
+    an existing repo) is left alone.
+    """
+    import shutil
+    import subprocess
+
+    git = shutil.which("git")
+    if git is None:
+        return GitResult(False, False, "git not installed")
+    inside = subprocess.run(  # noqa: S603 — fixed argv, git resolved via shutil.which
+        [git, "-C", str(target), "rev-parse", "--is-inside-work-tree"],
+        capture_output=True,
+        text=True,
+    )
+    if inside.returncode == 0 and inside.stdout.strip() == "true":
+        return GitResult(False, False, "already inside a git repository")
+    for argv in ([git, "init", "--quiet"], [git, "add", "--all"]):
+        step = subprocess.run(argv, cwd=target, capture_output=True, text=True)  # noqa: S603 — fixed argv
+        if step.returncode != 0:
+            return GitResult(True, False, step.stderr.strip() or f"git {argv[1]} failed")
+    commit = subprocess.run(  # noqa: S603 — fixed argv
+        [git, "commit", "--quiet", "-m", "Scaffold books with quints init"],
+        cwd=target,
+        capture_output=True,
+        text=True,
+    )
+    if commit.returncode != 0:
+        # Most likely no git identity — leave the repo with everything staged.
+        return GitResult(True, False, commit.stderr.strip() or "git commit failed")
+    return GitResult(True, True)

{quints-0.3.0 → quints-0.4.0}/src/quints/invoice/model.py

@@ -9,6 +9,7 @@ one contract.
 from __future__ import annotations
 
 import json
+import re
 import sys
 from datetime import date
 from decimal import ROUND_HALF_UP, Decimal
@@ -288,6 +289,20 @@ def load_mapping(path: Path) -> dict:
     raise ValueError(f"unsupported invoice file format {suffix!r} (use .yaml/.toml/.json)")
 
 
+def document_path(inv: Invoice, income_account: str, root: Path = Path("documents")) -> Path:
+    """Where the rendered PDF is filed, per the beancount documents convention.
+
+    `option "documents"` discovery wants `<root>/<Account/Tree>/YYYY-MM-DD.…`;
+    the date prefix is what links the file to the account, and the
+    `<payee>.<number>` tail keeps the folder scannable:
+    `documents/Income/…/Domestic/2026-07-02.acme-ag.INV2026014.pdf`.
+    """
+    customer = inv.customer.name if isinstance(inv.customer, Party) else inv.customer
+    slug = re.sub(r"[^a-z0-9]+", "-", customer.lower()).strip("-") or "customer"
+    name = f"{inv.issue_date.isoformat()}.{slug}.{inv.number}.pdf"
+    return root.joinpath(*income_account.split(":")) / name
+
+
 def load_issuer(path: Path) -> Issuer:
     return Issuer.model_validate(load_mapping(path))
 

{quints-0.3.0 → quints-0.4.0}/tests/test_docs.py

@@ -41,7 +41,10 @@ REPO = Path(__file__).resolve().parents[3]
 EXAMPLES = Path(__file__).resolve().parents[1] / "examples"
 
 DOC_PAGES = sorted(p.relative_to(REPO) for p in (REPO / "docs").rglob("*.md"))
-PAGES = [Path("README.md"), *DOC_PAGES]
+# The generated AGENTS.md is a doc page too — the one an agent actually reads.
+# Its fenced commands run against the example project like every other page.
+AGENTS_MD = EXAMPLES.relative_to(REPO) / "AGENTS.md"
+PAGES = [Path("README.md"), AGENTS_MD, *DOC_PAGES]
 
 _FENCE = re.compile(r"^```(\w*)")
 _NO_TEST = re.compile(r"<!--.*no-test.*-->")
@@ -110,3 +113,25 @@ def test_extractor_sees_the_docs() -> None:
     assert len(DOC_PAGES) >= 8, f"docs/ pages missing: found only {DOC_PAGES}"
     total = sum(len(_commands((REPO / p).read_text())) for p in PAGES)
     assert total >= 25, f"only {total} documented commands extracted — extractor broken?"
+    agents = len(_commands((REPO / AGENTS_MD).read_text()))
+    assert agents >= 5, f"AGENTS.md yields only {agents} runnable commands"
+
+
+def test_hosted_schemas_are_in_sync() -> None:
+    # The scaffold's yaml-language-server modelines point at
+    # <site>/schema/<name>.schema.json; the committed docs/schema/ files that
+    # publish there must match the Pydantic models. Regenerate: `make docs`.
+    import json
+
+    from quints.invoice import model as m
+
+    for name, mdl in (
+        ("invoice", m.Invoice),
+        ("issuer", m.Issuer),
+        ("customers", m.CustomerRegistry),
+    ):
+        path = REPO / "docs" / "schema" / f"{name}.schema.json"
+        assert path.exists(), f"{path} missing — run `make docs`"
+        assert json.loads(path.read_text()) == mdl.model_json_schema(), (
+            f"docs/schema/{name}.schema.json is stale — run `make docs`"
+        )

{quints-0.3.0 → quints-0.4.0}/tests/test_init.py

@@ -8,6 +8,7 @@ against it, asserting known figures. That is the end-to-end smoke test the CI
 
 import json
 import re
+import subprocess
 import sys
 from datetime import date as Date
 
@@ -210,10 +211,159 @@ def test_sample_invoices_render_and_reconcile(tmp_path: Path):
     assert cc.found and cc.ok and cc.date_ok
 
 
+def test_cli_scaffold_to_invoice_end_to_end(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+    # The exact steps a new user types, through the CLI: `quints init …
+    # --samples`, then `quints invoice` on each sample invoice inside the
+    # project. Guards the whole chain — invoicing/ lands on disk, quints.toml
+    # resolves from the cwd, the QR-bill renders, the ledger cross-check
+    # matches. Einzelfirma on purpose: its account namespace differs from the
+    # built-in defaults, so a config-resolution regression can't hide.
+    proj = tmp_path / "jane-books"
+    res = runner.invoke(
+        app,
+        [
+            "init",
+            str(proj),
+            "--name",
+            "Jane Doe",
+            "--legal-form",
+            "einzelfirma",
+            "--lang",
+            "en",
+            "--samples",
+        ],
+    )
+    assert res.exit_code == 0, res.output
+    for rel in (
+        "invoicing/issuer.yaml",
+        "invoicing/customers.yaml",
+        "invoicing/acme-2026-07.yaml",
+        "invoicing/globex-2026-08.yaml",
+    ):
+        assert (proj / rel).exists(), f"scaffold did not create {rel}:\n{res.output}"
+
+    monkeypatch.chdir(proj)
+    # Rendered invoices are filed per the beancount documents convention:
+    # documents/<income account tree>/<date>.<customer>.<number>.pdf.
+    income = proj / "documents/Income/CH/Einzelfirma/Consulting/External"
+    for invoice_file, filed in (
+        ("acme-2026-07", income / "Domestic/2026-07-02.acme-ag.INV2026014.pdf"),
+        ("globex-2026-08", income / "Export/2026-08-05.globex-ltd.INV2026015.pdf"),
+    ):
+        res = runner.invoke(app, ["invoice", f"invoicing/{invoice_file}.yaml"])
+        assert res.exit_code == 0, res.output
+        assert "Ledger match" in res.output, res.output
+        assert filed.exists(), res.output
+
+
 def test_no_invoicing_files_without_samples():
     assert not any(f.path.parts[0] == "invoicing" for f in init.plan(init.Answers()))
 
 
+def test_agent_payload_is_loaded_and_accurate():
+    # CLAUDE.md @-includes AGENTS.md so Claude Code sessions start with the
+    # instructions in context; the commands AGENTS.md quotes must be complete
+    # (konten needs a period), and the sample checklist only appears when
+    # there is sample data to replace.
+    files = _files(init.Answers(include_samples=True, importers=("ubs", "wise")))
+    assert files["CLAUDE.md"] == "@AGENTS.md\n"
+    agents = files["AGENTS.md"]
+    assert "quints report konten --year 2026" in agents
+    assert "Sample data — replace before the books are real" in agents
+    assert "QUINTS_WISE_API_TOKEN" in agents
+    assert "quints import stripe" not in agents  # only the configured roster
+    bare = _files(init.Answers())["AGENTS.md"]
+    assert "Sample data" not in bare
+    assert "quints.toml` (supported: ubs, wise, stripe)" in bare
+
+
+def test_invoicing_yaml_carries_hosted_schema_modeline():
+    files = _files(init.Answers(include_samples=True))
+    for name, schema in [
+        ("issuer.yaml", "issuer"),
+        ("customers.yaml", "customers"),
+        ("acme-2026-07.yaml", "invoice"),
+        ("globex-2026-08.yaml", "invoice"),
+    ]:
+        first = files[name].splitlines()[0]
+        assert first == (
+            f"# yaml-language-server: $schema={config.DOCS_URL}/schema/{schema}.schema.json"
+        ), f"{name} lacks the schema modeline: {first}"
+
+
+def test_gitignore_keeps_documents_tree_committed():
+    # A blanket *.pdf ignore would silently exclude documents/ — the filed
+    # sources and rendered invoices the ledger links to must be committable.
+    gitignore = _files(init.Answers())[".gitignore"]
+    assert "*.pdf" not in gitignore
+    assert "/staging/" in gitignore
+
+
+def test_cli_init_commits_pristine_scaffold(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+    # No git identity is configured in CI — provide one via the environment.
+    for var in ("GIT_AUTHOR_NAME", "GIT_COMMITTER_NAME"):
+        monkeypatch.setenv(var, "quints test")
+    for var in ("GIT_AUTHOR_EMAIL", "GIT_COMMITTER_EMAIL"):
+        monkeypatch.setenv(var, "test@example.invalid")
+    proj = tmp_path / "books"
+    res = runner.invoke(app, ["init", str(proj), "--yes", "--json"])
+    assert res.exit_code == 0, res.output
+    payload = json.loads(res.output)
+    assert payload["git"] == {"initialized": True, "committed": True, "detail": ""}
+    assert (proj / ".git").is_dir()
+    log = subprocess.run(  # noqa: S603 — fixed git argv in a test
+        ["git", "-C", str(proj), "log", "--format=%s"],  # noqa: S607
+        capture_output=True,
+        text=True,
+    )
+    assert log.stdout.strip() == "Scaffold books with quints init"
+    status = subprocess.run(  # noqa: S603 — fixed git argv in a test
+        ["git", "-C", str(proj), "status", "--porcelain"],  # noqa: S607
+        capture_output=True,
+        text=True,
+    )
+    assert status.stdout == ""  # the initial commit captured the whole scaffold
+
+
+def test_cli_init_never_nests_a_repo_inside_one(tmp_path: Path):
+    subprocess.run(["git", "init", "--quiet", str(tmp_path)], check=True)  # noqa: S603, S607
+    proj = tmp_path / "books"
+    res = runner.invoke(app, ["init", str(proj), "--yes", "--json"])
+    assert res.exit_code == 0, res.output
+    git = json.loads(res.output)["git"]
+    assert git["initialized"] is False and "already inside" in git["detail"]
+    assert not (proj / ".git").exists()
+
+
+def test_cli_init_no_git_opts_out(tmp_path: Path):
+    proj = tmp_path / "books"
+    res = runner.invoke(app, ["init", str(proj), "--yes", "--no-git", "--json"])
+    assert res.exit_code == 0, res.output
+    assert json.loads(res.output)["git"] is None
+    assert not (proj / ".git").exists()
+
+
+def test_cli_init_without_tty_aborts_cleanly_before_writing(tmp_path: Path):
+    # `init` prompts for unanswered questions; with no stdin (agent, script,
+    # CI) the prompt aborts — that must happen BEFORE anything is written, so
+    # a failed run never leaves a half-scaffolded project. Non-interactive
+    # callers pass the full flag set, --yes, or --answers.
+    proj = tmp_path / "books"
+    res = runner.invoke(app, ["init", str(proj), "--samples"])
+    assert res.exit_code != 0
+    assert not proj.exists()
+
+
+def test_cli_version_flag():
+    # `quints --version` must report the installed distribution's version —
+    # the first thing to check when a scaffold is missing newer files.
+    from importlib.metadata import version
+
+    res = runner.invoke(app, ["--version"])
+    assert res.exit_code == 0
+    assert res.output.strip() == version("quints")
+
+
 def test_cli_init_answers_file_and_force(tmp_path: Path):
     # Guards the CLI wiring: --answers is non-interactive, --json is stable,
     # and a second run without --force skips rather than clobbers.

quints-0.3.0/examples/.gitignore

@@ -1,8 +0,0 @@
-# quints working directories
-/staging/
-.env
-__pycache__/
-*.pdf
-.venv/
-.DS_Store
-.wise/

quints-0.3.0/examples/AGENTS.md

@@ -1,56 +0,0 @@
-# Working on Example GmbH's books with an AI agent
-
-These are plain-text ([beancount](https://beancount.github.io)) books managed
-with [`quints`](https://github.com/sealambda/quints). **`quints` is a
-deterministic tool — you drive it, it never calls a model.** Your job is to
-extend and maintain the ledger; `quints` validates and reports on it.
-
-## Setup
-
-`uv sync` once — it installs quints, which brings beancount and fava along.
-Then `uv run quints check` (or activate the venv and call `quints` and the
-standard beancount tools directly).
-
-## Layout
-
-- `main.bean` — options, plugins, includes; the entry point every tool loads.
-  `plugin "quints.plugins.kmu"` is enabled: every `*:CH:GmbH:*` account
-  **must** be opened with a four-digit `kmu:` code (Swiss KMU Kontenrahmen).
-- `accounts.bean` — the chart of accounts (all `open` directives).
-- `books/2026.bean` — transactions, one file per fiscal year. `main.bean`
-  includes `books/*.bean`, so a new year just needs a new file.
-- `commodities.bean` — currencies; `prices.bean` — FX rates, refresh with
-  `quints prices sync`.
-- `quints.toml` — entity config (name, legal form, VAT, importer rules). VAT
-  *rates* are law and live in code, not here.
-- `staging/` — importer drafts land here; `inbox/` — incoming source
-  documents; `documents/` — filed documents, mirroring the account tree.
-
-## Extending the chart of accounts (the part that needs judgement)
-
-Add income/expense sub-trees for this business as `open` directives in
-`accounts.bean`, each with the KMU code it rolls up to, e.g.:
-
-```beancount
-2026-01-01 open Expenses:CH:GmbH:Marketing:Ads CHF
-  kmu: "6600"  ; Advertising
-```
-
-Run `quints report konten` to see the codes already in use. Pick codes from the
-KMU Kontenrahmen; `quints check` fails on a `:CH:GmbH:` account with no valid
-`kmu:` code.
-
-## The loop
-
-1. Draft bank/PSP activity: `quints import ubs <file>` → `staging/`.
-2. Review, add the VAT decision (InputVAT / Bezugsteuer / none) and a linked
-   document, then move drafts into `books/2026.bean`.
-3. **Always** `quints check` before you consider the books consistent.
-
-## Machine-readable surfaces (prefer these over scraping text)
-
-- Every reporting command takes `--json`: `quints mwst -q 2026-Q3 --json`,
-  `quints status --json`, `quints report bilanz --json`.
-- `quints schema` writes JSON Schemas for the invoice/issuer/customer files.
-
-Never invent VAT numbers or rates — compute them with `quints mwst`.

quints-0.3.0/src/quints/__init__.py

@@ -1,3 +0,0 @@
-"""quints — Swiss VAT & accounting for plain-text (beancount) books."""
-
-__version__ = "0.3.0"