bobina 0.1.0__tar.gz

bobina-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+      - name: Lint
+        run: |
+          ruff check src tests tools
+          ruff format --check src tests
+      - name: Tests (no printer needed)
+        run: pytest -q
+
+  privacy:
+    # Generic patterns for everyone; the owner's personal patterns come from a secret, which GitHub does not give
+    # to pull requests from forks (so a fork's PR gets the generic scan, and main is scanned again after merge).
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Personal-data scan of the files
+        env:
+          LEAK_PATTERNS: ${{ secrets.LEAK_PATTERNS }}
+        run: python tools/leakscan.py
+      - name: Personal-data scan of the commit messages
+        env:
+          LEAK_PATTERNS: ${{ secrets.LEAK_PATTERNS }}
+          BEFORE: ${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha || github.event.before }}
+        run: |
+          if [ -z "$BEFORE" ] || ! git cat-file -e "$BEFORE" 2>/dev/null; then range="HEAD~1..HEAD"; else range="$BEFORE..HEAD"; fi
+          git rev-parse -q --verify HEAD~1 >/dev/null || range="HEAD"
+          git log --format='%B' "$range" > "$RUNNER_TEMP/messages.txt"
+          python tools/leakscan.py "$RUNNER_TEMP/messages.txt"

bobina-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,104 @@
+# A version is a tag, published to PyPI by trusted publishing (no token) and installed on Linux, macOS and Windows.
+# vX.Y.Z-rc.N is a pre-release (0.1.0rc1): pip and uv only install it when asked by version or with --pre, so
+# nobody gets it by accident; it becomes a GitHub pre-release. vX.Y.Z is the release.
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    if: github.event.repository.private == false  # only the public repository releases
+    runs-on: ubuntu-latest
+    outputs:
+      prerelease: ${{ steps.version.outputs.prerelease }}
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: The tag matches the version in pyproject.toml
+        id: version
+        run: |
+          python -m pip install --quiet packaging  # not in the runner's Python
+          tag="${GITHUB_REF_NAME#v}"
+          want=$(python -c "from packaging.version import Version; print(Version('$tag'))")
+          have=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          have=$(python -c "from packaging.version import Version; print(Version('$have'))")
+          [ "$want" = "$have" ] || { echo "::error::tag $GITHUB_REF_NAME is $want, pyproject.toml says $have"; exit 1; }
+          echo "version=$want" >> "$GITHUB_OUTPUT"
+          case "$GITHUB_REF_NAME" in *-*) echo "prerelease=true" >> "$GITHUB_OUTPUT";; *) echo "prerelease=false" >> "$GITHUB_OUTPUT";; esac
+      - name: Tests and personal-data scan
+        env:
+          LEAK_PATTERNS: ${{ secrets.LEAK_PATTERNS }}
+        run: |
+          python -m pip install -e ".[dev]" build
+          pytest -q
+          python tools/leakscan.py
+      - name: Build
+        run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  install-test:
+    needs: [build, pypi]
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install this version from PyPI and run it
+        shell: bash
+        run: |
+          for i in 1 2 3 4 5 6; do
+            python -m pip install "bobina==${{ needs.build.outputs.version }}" && break
+            sleep 20  # the index takes a moment to show a new upload
+          done
+          bobina --version
+          bobina check "hello from the release check" --json
+
+  github-release:
+    needs: [build, pypi, install-test]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Release with the CHANGELOG section
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          v="${{ needs.build.outputs.version }}"
+          base=$(python3 -c "import re,sys; print(re.sub(r'(a|b|rc)\d+$', '', sys.argv[1]))" "$v")  # 0.1.0rc1 -> 0.1.0
+          awk -v v="$base" '$0 ~ "^## "v" " || $0 ~ "^## "v"$" {on=1; next} on && /^## / {exit} on' CHANGELOG.md > notes.md
+          [ -s notes.md ] || echo "bobina $v" > notes.md
+          pre=""; [ "${{ needs.build.outputs.prerelease }}" = "true" ] && pre="--prerelease"
+          gh release create "$GITHUB_REF_NAME" dist/* --title "bobina $v" --notes-file notes.md $pre

bobina-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+# artefatos grandes/baixados ficam fora do git; o manifesto registra hash e origem
+artifacts/
+*.apk
+*.xapk
+*.bin
+!teste.bin
+!minimo.bin
+__pycache__/
+.remember/
+local/
+.venv/
+*.egg-info/
+.pytest_cache/
+tests/out/
+security-audit-runs/
+build/
+.claude/

bobina-0.1.0/AGENTS.md

@@ -0,0 +1,40 @@
+# Notes for coding agents
+
+bobina is a Python CLI (src/bobina) that prints Markdown on thermal roll printers. Read CONTRIBUTING.md first: it
+has the rules that tests enforce.
+
+## Every change
+
+```bash
+.venv/bin/pytest -q                                 # no printer needed
+.venv/bin/ruff check src tests tools && .venv/bin/ruff format src tests tools
+.venv/bin/python tools/leakscan.py                  # no personal data: runs in CI
+```
+
+- Rendering changes: `BOBINA_UPDATE_GOLDEN=1 pytest tests/test_golden.py`, then look at every changed PNG.
+- Docs have a token budget per page (tests/test_token_budget.py): over it, split or cut the page.
+- Docs that are generated, never edited by hand: `docs/diagrams/nudges-flow.md` and `docs/problems/`
+  (`tools/gen_problem_docs.py`),
+  `docs/pay.md` (`tools/gen_pay_docs.py`), `llms-full.txt` (`tools/gen_llms_full.py`), imported printer profiles (`tools/import_profiles.py`).
+- A new command or option: `COMMAND_KIND`, `ALSO_KNOWN`/`NO_SYNONYMS` in `src/bobina/cli/args.py` and a hint case
+  in `tests/test_option_hints.py` (a test fails until done). A new problem code: `CATALOG` in `src/bobina/nudges.py`,
+  what to do in `FIX` (`src/bobina/problem_help.py`), the table in `docs/FORMAT.md`, then `tools/gen_problem_docs.py`.
+
+## Principles
+
+- Nudges, not blocks: warn with a code, a suggestion and the evidence; refuse only for security.
+- Printer facts come from paper: a profile value needs a printed test (docs/printers/). Imported profiles are
+  `measured = false` and conservative.
+- Full command names in docs and output; English in code and docs.
+- Never print on a real printer from tests: use `-o`, `--dry-run`, `check`, `preview` or a file printer
+  (`bobina printer add test --path out.bin`).
+
+## Map
+
+| Path | What |
+|---|---|
+| `src/bobina/engine.py`, `layout.py` | document → rows (native text, raster, codes, feeds) |
+| `src/bobina/escpos.py`, `transport.py` | rows → bytes; Bluetooth, file and command transports |
+| `src/bobina/cli/` | commands (`args.py` parser, `documents.py` print/check/preview, `device.py` printer/calibrate) |
+| `src/bobina/profiles/` | printer profiles (TOML) and their sources |
+| `evals/agent-eval.yaml` | agent tasks for cli-agent-eval (how well agents use this CLI) |

bobina-0.1.0/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog
+
+## 0.1.0 — 2026-11-10
+
+First version, calibrated on a Goldensky MTP-II (58 mm).
+
+- Printer profiles: 32 more, generated from escpos-printer-db (CC BY 4.0) by `tools/import_profiles.py`: model facts
+  only, `measured = false`, conservative (ASCII native text, raster barcodes, safe mode) until `bobina calibrate tear`
+  and `bobina calibrate feed`; `bobina profile list` says which are measured. Sources: `src/bobina/profiles/SOURCES.md`.
+- `--marks none|cut|tear|both`: a fine dashed line where one label or order ends (none by default).
+- Payment codes: the ```` ```pay ```` block, one set of fields (`to`, `name`, `amount`, `ref`, `note`) for 15 schemes
+  (Pix, UPI, SEPA/EPC, PromptPay, PayNow, bitcoin, lightning, PayPal, Cash App, Venmo, Revolut, Wise, PicPay,
+  Mercado Pago, and `other` for a pasted payload). Pix is `pay {scheme=pix}`; template `pay-sign`. `bobina help pay SCHEME` (and
+  docs/pay.md) says what each field means in that scheme, its official name and its limit. A value over a limit
+  is `Q111`, never cut. Only Pix was scanned with real apps; the others carry the note `P302`.
+- Any ```` ```qr ```` takes `caption=`: `auto` under a payment code ("Pix · R$ 10,00"), `none`, or your own text.
+- Money without a `locale:` is written as the currency's country does (R$ 24,90, ₹120.00), not as the system
+  LANG would (R$24.90 on an en_US machine). A document that declares `locale:` keeps its own.
+- Exit code 9: the job went out without its payment code (`Q111`); the rest printed. `--allow Q111` gives 0.
+- `print --json` and `preview --json` write the outcome, the figures and the problems (schemas `bobina.print/1`,
+  `bobina.preview/1`); before, `print --json` hid the warnings. `paper` and `calibrate tear|feed` answer in JSON
+  too; `view`, `edit`, `send` and `mode` say that `--json` does nothing there.
+- `bobina help CODE` (what a problem means and what to do, docs/problems/), `bobina help --json` (commands,
+  options, topics, problems and exit codes for programs), `llms.txt`, `llms-full.txt` and an agent skill
+  (`skills/bobina`).
+- Templates for shops: `clothing-tag`, `jewelry-tag`, `shelf-price`, `sale-price`, `food-label`, `shipping-label`
+  (docs/guides/templates.md); prices typed as people type them (`24,90`, `R$ 1.890,00`), `M202` when a value is
+  not a number. Notes `P301` (a feature not tested on paper yet) and `P302` (a payment code not tested in its app).
+- Safe by default for printers nobody measured: feeds after images as white raster rows, idle wait before the end
+  of an image job; `bobina calibrate feed` turns it off for printers that do not need it.
+
+- Speed and memory: each QR is encoded once (cache), a batch decodes a logo once (per-file cache keyed by size and
+  modification time), big JPEGs are decoded reduced (6000x4000 target: 250 MB -> 72 MB); `--pages` writes the PDF
+  page by page at 1:1 (copies share one image); image export draws each label once.
+- Long jobs: previews drawn page by page and split above ~2.5 m (1000 labels: 422 MB -> 88 MB); a print keeps only
+  the shown labels' preview for `--last` (425 MB -> 68 MB); 1-bit PNGs. Bounded waits: download deadline and DNS
+  timeout, device-file and bluetoothctl timeouts, stdin size caps, `BOBINA_NONINTERACTIVE=1`.
+- Concurrency: a print reserves its seq numbers when it is built (given back when it is not printed and nobody took
+  later ones), one job per printer at a time (`busy_timeout`, `E405`), and every state file (counters, paper,
+  history, library, config, last job, exports) is written atomically under a lock; a damaged one is `E209`.
+- `.bob.md`: Markdown + Pandoc attributes, fenced objects (QR, barcodes, payment codes, Data Matrix, PDF417, images,
+  raw bytes), Jinja variables in a sandbox, CLDR dates/numbers per locale, persistent counters, templates.
+- Engine: one set of print rows feeds the exact preview and the ESC/POS bytes; native when the printer does it
+  well, raster per line when it does not; host word wrap; printer-font emulation for previews.
+- CLI: `print` with a confirmation screen (`--yes` to skip), `check`, `preview` (`--realistic`), `view`, `edit`,
+  `template`, `seq`, `printer`, `status`, `mode`, `paper` (roll odometer), `calibrate compare|tear|feed`, `fonts`.
+- Spacing attributes: `tracking=` (letter spacing), `indent=` (columns or mm/px), `leading=` (line spacing), in the
+  printer font (`ESC SP`, `ESC 3`) and in raster fonts.
+- Text filters: `titlecase` (by language), `deaccent`, `camel`, `pascal`, `snake`, `kebab`, `slug`, `smallcaps`; also
+  in export names (`{item|slug}`). Security: filters, string methods and joins keep data marked (no image path
+  from data through `| lower` or `'img/' ~ value`).
+- `bobina history` (list, show, stats, clear): every print job recorded privately (schema `bobina.history/1`).
+- `--problems pretty|plain|json|jsonl` (or `BOBINA_PROBLEMS`): every error and warning, also usage errors, in a
+  stable schema (`bobina.problem/1`) for scripts and logs.
+- Export: `-o` with `{n}`, `{i}`, `{file}`, `{part}`, `{column}` saves one file per label (printer bytes from
+  `print`, images from `preview`); `preview --pages -o x.pdf` makes one page per label.
+- Several data sources: `--data a=FILE --join b=FILE --on KEY` (left join; bare column names when unambiguous,
+  `{{ b.col }}` to choose; warnings for unmatched/duplicate keys and shared columns).
+- Every problem has a code: errors `E1xx`–`E5xx` join the nudge catalog; one format for all of them.
+- One strip: several files and `--then` parts in one job (one preview, confirmation and paper count);
+  `--compact`/`--no-compact` per part and `--compact-all`; ✂ cut lines inside compact parts and between two
+  compact parts, the tear feed elsewhere; counters continue across parts.
+- Data for batches: `--data` reads CSV, TSV/TXT (delimiter detected, cp1252 fallback), Excel `.xlsx`
+  (`--sheet`, `bobina[xlsx]`) and JSON; `--rows`, `--where`, `--copies-from` (copies per row).
+- Saved labels: `bobina library add|list|show|rm` and `bobina print @NAME` (with `--set`/`--ask`).
+- `--ask`: the missing template fields (or a document's undeclared `{{ variables }}`) are asked on the
+  terminal, with help, examples, defaults and table rows; answers are literal data like `--set`.
+- Images: SVG and PDF pages rendered at the paper width (`bobina[svg]`, `bobina[pdf]`); `bobina print`
+  takes a photo, SVG, PDF (`--page N-M`) or https image directly; https images only with `--allow-net`,
+  public hosts only (see `docs/SECURITY.md`).
+- Codes fill the paper: `size=full|half` for QR/Data Matrix, stretched barcodes, long barcodes turned vertical.
+- Safety: data from CSV/`--set` is literal (no Markdown, template or printer-command injection), template paths
+  confined, sandbox limits; see `docs/SECURITY.md`.
+- Profile `mtp-ii-58` with measured limits (`docs/printers/mtp-ii-58.md`) and conformance tickets
+  (`spec/conformance/`).

bobina-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# Contributing
+
+- `python -m pip install -e ".[dev]"`, then `pytest -q` and `ruff check src tests && ruff format src tests`.
+  No printer is needed: tests compare exact bitmaps (`tests/golden/`, `spec/conformance/`).
+- An intended rendering change regenerates the bitmaps with `BOBINA_UPDATE_GOLDEN=1 pytest tests/test_golden.py`;
+  look at every changed PNG before committing.
+- New printer? Copy `src/bobina/profiles/mtp-ii-58.toml`, print the conformance tickets, photograph them, and
+  record what works in `docs/printers/<id>.md`. Defaults must come from printed evidence.
+- Principles: nudges, not blocks (warn with a suggestion and the evidence, never refuse — except security);
+  full command names in docs and output; English everywhere.
+- Never commit personal data: `python tools/leakscan.py` runs in CI on every push and pull request.
+  `tools/install-hooks.sh` installs the same scan as git hooks (staged files and commit messages).
+- Releases are tags (`.github/workflows/release.yml`): each one is published to PyPI, installed on Linux, macOS and
+  Windows, and becomes a GitHub release. `vX.Y.Z-rc.N` is a pre-release (only installed when asked for). The tag must match the version
+  in `pyproject.toml` (`0.2.0rc1` for `v0.2.0-rc.1`), and CHANGELOG.md gets a `## 0.2.0` section first.
+
+## A new command or option
+
+A test fails until each step is done, so nothing is forgotten when the CLI grows:
+
+1. **Kind of command**: add it to `COMMAND_KIND` in `src/bobina/cli/args.py`: `prints` (it takes `--yes`,
+   `--dry-run`, `--editor`) or `reads` (it never prints; those options are not listed in its help and, if given,
+   only a note says they do nothing).
+   Without it, building the parser raises an error that says this.
+2. **Synonyms of each new long option**: what people type for it (English and Portuguese) in `ALSO_KNOWN`, or the
+   option in `NO_SYNONYMS` when its own name is what people type. No word may be a synonym of two options.
+3. **Hint cases**: at least one realistic mistyped option for each new command in `CASES`
+   (`tests/test_option_hints.py`).
+4. Typos of every option of every command (swapped neighbours, a dropped letter, `_` for `-`, upper case, one dash)
+   are tested automatically; nothing to add.
+
+## A new problem code
+
+Add it to `CATALOG` (`src/bobina/nudges.py`), say what to do in `FIX` (`src/bobina/problem_help.py`) and add it to
+the table in `docs/FORMAT.md`, then run `python tools/gen_problem_docs.py` (the flow diagram and docs/problems/).
+`tests/test_docs.py` and `tests/test_problem_help.py` check them.

bobina-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rafael Bressan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bobina-0.1.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.5
+Name: bobina
+Version: 0.1.0
+Summary: Print Markdown on thermal roll printers, with calibrated defaults, previews you can trust and nudges instead of blocks.
+License-Expression: MIT
+License-File: LICENSE
+License-File: src/bobina/fonts/licenses/AtkinsonHyperlegible-OFL.txt
+License-File: src/bobina/fonts/licenses/Barlow-OFL.txt
+License-File: src/bobina/fonts/licenses/DejaVu-LICENSE.txt
+License-File: src/bobina/fonts/licenses/IBMPlex-OFL.txt
+License-File: src/bobina/fonts/licenses/Spleen-BSD-2.txt
+License-File: src/bobina/fonts/licenses/Terminus-OFL.txt
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Printing
+Requires-Python: >=3.11
+Requires-Dist: babel>=2.12
+Requires-Dist: fonttools>=4.40
+Requires-Dist: jinja2>=3.1
+Requires-Dist: markdown-it-py>=3
+Requires-Dist: mdit-py-plugins>=0.4
+Requires-Dist: pdf417gen>=0.7
+Requires-Dist: pillow>=10
+Requires-Dist: ppf-datamatrix>=0.2
+Requires-Dist: python-barcode>=0.15
+Requires-Dist: pyyaml>=6
+Requires-Dist: segno>=1.6
+Provides-Extra: dev
+Requires-Dist: openpyxl>=3.1; extra == 'dev'
+Requires-Dist: pypdfium2>=5.14; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: resvg-py>=0.5; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: pdf
+Requires-Dist: pypdfium2>=5.14; extra == 'pdf'
+Provides-Extra: svg
+Requires-Dist: resvg-py>=0.5; extra == 'svg'
+Provides-Extra: xlsx
+Requires-Dist: openpyxl>=3.1; extra == 'xlsx'
+Description-Content-Type: text/markdown
+
+# bobina
+
+Print Markdown on thermal roll printers — receipts, lists, labels, QR codes, payment codes (Pix, UPI, SEPA…), photos —
+with calibrated defaults, a preview you can trust, and **nudges instead of blocks**.
+
+```bash
+bobina print "# MARKET\n- [ ] milk\n- [ ] bread"
+bobina print list.bob.md
+bobina template new receipt sale.bob.md && bobina print sale.bob.md
+```
+
+Every command that prints shows a **confirmation screen** first (the dry run): a terminal preview
+on the real 32-column grid, paper length, counters it will use, and nudges with the evidence
+behind them. `p` prints; `--yes` skips it. **Without a terminal (scripts, agents, ssh) add `--yes`**:
+otherwise nobody can answer and the print stops with `E107` (exit 7). `-n` shows the screen and prints nothing.
+Agents: start at [llms.txt](llms.txt) (or [llms-full.txt](llms-full.txt), everything in one file); a ready skill
+is in [skills/bobina/SKILL.md](skills/bobina/SKILL.md).
+
+```
+┌─ preview · mtp-ii-58 · 58 mm ──┐
+│                                │
+│M A R K E T                     │
+│                                │
+│☐  milk                         │
+│☐  bread                        │
+└────────────────────────────────┘
+ ~3.1 cm of paper · 1 native rows, 2 raster · 2.9 KB
+ [p] print   [s] save as…   [q] quit
+```
+
+## Why
+
+Cheap 58/80 mm printers are good enough for a lot — if something takes care of their limits.
+bobina was calibrated on a minimum-quality printer (Goldensky MTP-II): every default comes from
+a printed and photographed test, so what works there works on better printers. You can ask for
+anything; bobina only warns, and tells you why (`warning[Q101] … (evidence: N6)`).
+
+- **One engine** for check, preview and print: the PNG preview is the exact dot pattern sent.
+- **Native when the printer does it well, raster when it does not** — per line, decided by the
+  printer profile (glyphs the font lacks, italic, inverted bands, drawn checkboxes).
+- **Readable documents**: plain Markdown plus Pandoc-style attributes. See [docs/FORMAT.md](docs/FORMAT.md).
+- **Safe data**: values from CSV or `--set` are printed literally and can never inject Markdown,
+  template code or printer commands; templates run in a sandbox.
+
+## Install
+
+```bash
+uv tool install bobina        # or: pipx install bobina   (from a checkout: ./install.sh)
+bobina printer scan           # find the Bluetooth address
+bobina printer add mtp AA:BB:CC:DD:EE:FF
+bobina status                 # paper, cover, errors
+```
+
+Printer on another machine? `bobina printer add tower --command "ssh tower bobina send --yes -"`.
+No printer at hand? `bobina printer add test --path out.bin` appends every job's bytes to `out.bin` (a file
+printer: `status` and `paper` need Bluetooth; `bobina printer list` shows where each printer goes).
+
+## The format in one screen
+
+````markdown
+---
+locale: pt-BR
+counters:
+  ticket: { start: 1, format: "A-{:03}" }
+fonts:
+  body: native                 # the printer's own font (fast)
+  hand: Z003                   # any alias you like
+---
+# TICKET {{ seq.ticket }} {.invert .center}
+
+{{ now | date("full") }}        <!-- quinta-feira, 5 de novembro de 2026 -->
+
+- [ ] open task
+- [x] done task (struck)
+
+| Item | Qty | Price |
+|---|--:|--:|
+| Bread | 6 | {{ 4.8 | currency("BRL") }} |
+
+```qr
+https://example.com
+```
+
+```pay {scheme=pix to="you@example.com" name="Shop" city="Rio" amount=10.00}
+```
+
+Signed, [Ana]{font=hand size=32px}
+
+--- {.cut}
+````
+
+`bobina help format` has the rest: sizes (`small`…`huge`, physical mm), dividers, barcodes,
+Data Matrix, PDF417, images (dither and gamma), rotation, upside-down text, templates and data.
+
+## One label per row
+
+A document with `{{ blanks }}` plus a table (CSV, TSV, JSON, Excel) prints one label per row; the
+columns fill the blanks. Step by step: [docs/guides/batch-printing.md](docs/guides/batch-printing.md);
+in the terminal: `bobina help data`.
+
+```bash
+bobina check jar-label.bob.md --data pantry.csv                 # paper length and problems, nothing printed
+bobina print jar-label.bob.md --data pantry.csv --where shelf=A --copies-from jars --yes
+bobina print tag.bob.md --data stock.xlsx --sheet Estoque --yes  # a sheet other than the first
+bobina print shelf-tag.bob.md --data a=prices.xlsx --join b=catalog.json --on name --yes
+bobina print note.bob.md --set produto=Feijão --set validade=2027-01-31 --yes   # one value, no table
+bobina preview jar-label.bob.md --data pantry.csv -o 'labels/{product}.png'    # one PNG per label
+```
+
+A `{{ name }}` that is not a column prints empty and is reported (`M130`, with the columns the data has).
+
+## Commands
+
+| Command | Does |
+|---|---|
+| `print [FILE \| "TEXT" \| -]` | render → confirm → print. `--data rows.csv` (above), `--set KEY=VALUE`, `--copies N` (identical), `--repeat N` (new counter values each), `-o job.bin` (save, do not print) |
+| `print --last` / `--again` | reprint the last job: identical bytes / re-rendered (new `now` and counters); with `-o FILE` save instead |
+| `check FILE` | problems, paper length, native/raster rows, nothing printed (`--data`, `--json` → `{"stats", "problems"}`, `--strict`) |
+| `preview FILE \| "TEXT"` | exact PNG (`-o out.png`); `--data rows.csv -o 'dir/{column}.png'` one per label; `--realistic` simulates ink spread |
+| `view FILE` | preview in the terminal |
+| `edit [FILE] [--template NAME]` | write in your editor, confirm, print |
+| `template list \| show \| new` | receipt, label, todo, card, note, and a shop gallery: [guides/templates.md](docs/guides/templates.md) |
+| `seq list \| set \| reset` | persistent counters (`{{ seq.NAME }}`); `seq set ticket 100`: the next print uses 100 |
+| `printer scan \| add \| list \| use \| remove` | printers live in `~/.config/bobina/config.toml` |
+| `status`, `mode [esc\|tspl\|cpcl]` | printer state; command language |
+| `calibrate compare PHOTO FILE` | how close the preview is to the paper |
+| `calibrate tear` / `calibrate feed` | where the tear bar is; whether feeds after images need the safe mode |
+| `paper [new 15m \| used 3m]` | paper left on the roll (the printer only reports "out") |
+| `profile list \| show`, `fonts list`, `send FILE.bin` | profiles, tested fonts, raw bytes |
+
+`bob` is the same binary. Short aliases exist for typing (`bobina help aliases`); docs always use
+full names. Exit codes: 0 ok · 1 usage · 2 document · 3 strict nudges · 4 unreachable · 5 printer
+not ready · 6 language · 7 confirmation needed/declined · 8 security · 9 a payment code left out (Q111).
+
+## Repository
+
+| Path | What |
+|---|---|
+| `src/bobina/` | the package (engine, layout, ESC/POS, preview, CLI) and built-in profiles, templates, fonts |
+| `docs/` | [`FORMAT.md`](docs/FORMAT.md) (the `.bob.md` spec), [`CLI.md`](docs/CLI.md) (commands, options, problems, exit codes), [`SECURITY.md`](docs/SECURITY.md) (threat model), [`guides/batch-printing.md`](docs/guides/batch-printing.md), [`TESTED.md`](docs/TESTED.md) (what was and was not tested on paper) |
+| `examples/` | documents and data used by the guides (`examples/batch/`) |
+| `spec/conformance/` | test tickets with expected bitmaps — a `bob/1` implementation renders them identically |
+| `tests/` | unit, security and golden tests (no printer needed) |
+| `docs/printers/` | measured capabilities of each profiled printer (`mtp-ii-58.md`) |
+| `contrib/` | Bluetooth boot service for Linux (`install.sh` sets it up) |
+| `tools/` | maintenance scripts: public export and personal-data scan |
+
+## Status
+
+Pre-release (v0.x). MIT licensed (bundled fonts keep their own licenses: `src/bobina/fonts/LICENSES.md`). Baseline profile: `mtp-ii-58` (measured); 32 more imported from escpos-printer-db, not measured on paper (`bobina profile list`; calibrate before trusting them). Realistic preview is an estimate until
+the profile is calibrated from photos (`preview.calibrated = false`).
+
+## Hardware notes (MTP-II)
+
+| Symptom | Likely cause |
+|---|---|
+| `printer unreachable` | printer off or asleep: press POWER until the yellow LED is steady |
+| Blank output | roll upside down (the side that darkens with a fingernail faces the head) |
+| Turns off when printing | battery: charge it; first use: remove the film on the battery contacts |
+| Prints garbage | another app sent a different command language (TSPL/CPCL) as text; the MTP-II itself only speaks ESC/POS |
+| Self-test | printer off → hold FEED, press POWER, release at the beep |
+| The last line stops at the tear bar, or a `--marks tear` line is off | `bobina calibrate tear` (a ruler: tear it and read the mm), then `bobina calibrate feed` (does the printer obey a paper feed right after an image?) |