nepkit 0.1.0__tar.gz

nepkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kritagya
+
+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.

nepkit-0.1.0/PKG-INFO

@@ -0,0 +1,350 @@
+Metadata-Version: 2.4
+Name: nepkit
+Version: 0.1.0
+Summary: Typed Bikram Sambat ↔ Gregorian date conversion, as a library and a CLI.
+Keywords: nepal,bikram-sambat,nepali-date,calendar,cli
+Author: Kritagya
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Dist: typer>=0.15,<0.28
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/akakritagya/nepkit
+Project-URL: Issues, https://github.com/akakritagya/nepkit/issues
+Project-URL: Repository, https://github.com/akakritagya/nepkit
+Description-Content-Type: text/markdown
+
+# nepkit
+
+```text
+                      _     _  _
+ _ __    ___   _ __  | | __(_)| |_
+| '_ \  / _ \ | '_ \ | |/ /| || __|
+| | | ||  __/ | |_) ||   < | || |_
+|_| |_| \___| | .__/ |_|\_\|_| \__|
+              |_|
+```
+
+Typed Bikram Sambat ↔ Gregorian date conversion for Python, as a library and a
+command-line tool.
+
+> **Status:** first release. The library and CLI both work and are tested; the
+> API may still change before 1.0.
+
+[**DEMO.md**](https://github.com/akakritagya/nepkit/blob/main/DEMO.md) walks
+through every command, option, and failure mode with real captured output.
+
+## Why
+
+Bikram Sambat is Nepal's official calendar, and converting to and from it is not
+arithmetic. Gregorian leap years follow a rule you can write down; BS month
+lengths do not. They vary between 29 and 32 days with no generating formula, are
+fixed by observation, and are published by Nepal's Panchanga authority. Every
+correct converter is therefore a **lookup table plus one verified anchor date** —
+which means the data matters more than the code, and most of the work in this
+repo went into the data.
+
+The existing Python options are small, mostly unmaintained packages with
+undocumented year ranges, no type hints, and no statement of where their numbers
+came from or how far they can be trusted. nepkit aims to be one typed, tested
+converter that is explicit about all three.
+
+## Install
+
+Requires Python 3.12+.
+
+```bash
+pip install nepkit       # library and CLI
+uv add nepkit            # into a uv project
+uv tool install nepkit   # the CLI on its own, isolated
+```
+
+[Typer](https://typer.tiangolo.com/) is the only direct dependency. The
+calendar table is bundled, so nepkit never touches the network.
+
+## Library
+
+```python
+from datetime import date
+
+from nepkit import BSDate, ad_to_bs, bs_to_ad
+
+bs_to_ad(BSDate(2081, 4, 15))  # date(2024, 7, 30)
+ad_to_bs(date(2024, 7, 30))  # BSDate(year=2081, month=4, day=15)
+```
+
+`BSDate` validates on construction, so if you are holding one it is a real date
+in the supported range:
+
+```python
+from nepkit import BSDate, days_in_month
+
+days_in_month(2081, 4)  # 32
+days_in_month(2081, 9)  # 29
+
+BSDate(2081, 4, 33)  # raises InvalidDateError
+BSDate(2081, 13, 1)  # raises InvalidDateError
+BSDate(2095, 1, 1)  # raises DateOutOfRangeError
+```
+
+`ad_to_bs` takes a `datetime.date`, so a malformed Gregorian date is impossible
+by construction — Python's own constructor rejects it before nepkit is involved.
+
+### Errors
+
+```text
+NepkitError
+├── CalendarDataError   the bundled table is malformed; raised at import
+└── DateError
+    ├── InvalidDateError      not a real BS date (month 13, day 33, ...)
+    └── DateOutOfRangeError   a real date, but outside the bundled range
+```
+
+The split between the last two is the one that earns its keep. BS 2095-03-12 is
+a perfectly real date that nepkit simply has no data for, and a caller can
+reasonably catch that and fall back or report the supported range. BS 2081-13-01
+is not a date at all, and catching it is always a mistake. Catch `DateError` if
+you only need "the user gave me something I can't convert".
+
+## CLI
+
+Installing puts a `nepkit` command on your PATH:
+
+```console
+$ nepkit bs2ad 2081-04-15
+2024-07-30
+
+$ nepkit ad2bs 2024-07-30
+2081-04-15
+
+$ nepkit today
+BS 2083-04-26
+AD 2026-08-11
+
+$ nepkit range
+BS 2000-01-01 .. 2090-12-30  (years 2000-2090)
+AD 1943-04-14 .. 2034-04-13
+```
+
+Direction is always explicit, and has to be: the BS and AD year numbers overlap
+from 2000 to 2034, so `2024` is a valid year in both calendars and nothing
+could reliably guess which one you meant.
+
+### Interactive
+
+Run `nepkit` with no arguments in a terminal and it clears the screen and opens
+a session:
+
+```console
+$ nepkit
+                      _     _  _
+ _ __    ___   _ __  | | __(_)| |_
+| '_ \  / _ \ | '_ \ | |/ /| || __|
+| | | ||  __/ | |_) ||   < | || |_
+|_| |_| \___| | .__/ |_|\_\|_| \__|
+              |_|
+nepkit v0.1.0 - Bikram Sambat (BS) <-> Gregorian (AD) date conversion
+Today  BS 2083-04-26   AD 2026-08-11
+
+Type a command, 'help', 'clear', or 'quit'.  Up/Down recalls history.
+
+nepkit> today
+BS 2083-04-26
+AD 2026-08-11
+
+nepkit> bs2ad 2081-04-15
+2024-07-30
+
+nepkit> quit
+```
+
+It accepts exactly the commands above — the same table, not a parallel
+interface — so anything you can type at the shell works here unchanged. A bad
+line reports the error and returns you to the prompt rather than ending the
+session. `clear` (or `cls`) wipes the screen and redraws the banner. `quit`,
+`exit`, `q`, and Ctrl-D all leave; Ctrl-C abandons the current line only.
+
+Those four are prompt-only words, not subcommands — `nepkit clear` at a shell
+stays a usage error rather than clearing your terminal.
+
+Up and Down recall previous commands, and the usual `readline` editing keys
+work (Ctrl-A, Ctrl-E, Ctrl-R, and so on). History lasts for the session and is
+not written to disk. On Windows, where Python ships no `readline`, the prompt
+works exactly the same minus the editing keys.
+
+**Only on a terminal.** With stdin redirected — a pipeline, a script, CI —
+`nepkit` prints help and exits 2 exactly as before, so nothing ever blocks
+waiting for a prompt that isn't there.
+
+### Calendars
+
+```console
+$ nepkit calbs 2081 4
+        Shrawan 2081
+    16 Jul - 16 Aug 2024
+Sun Mon Tue Wed Thu Fri Sat
+          1   2   3   4   5
+  6   7   8   9  10  11  12
+ 13  14  15  16  17  18  19
+ 20  21  22  23  24  25  26
+ 27  28  29  30  31  32
+
+$ nepkit calad 2024 7
+         July 2024
+Ashadh 17 - Shrawan 16, 2081
+Sun Mon Tue Wed Thu Fri Sat
+      1   2   3   4   5   6
+  7   8   9  10  11  12  13
+ 14  15  16  17  18  19  20
+ 21  22  23  24  25  26  27
+ 28  29  30  31
+```
+
+Both default to the current month. A Gregorian month never lines up with a BS
+month, so the subtitle names both ends of the span rather than pretending a
+single corresponding month exists.
+
+Grids are boxed and coloured on a terminal and plain when redirected, following
+the same convention as `ls` and `git`. Force it either way with
+`--color always|never|auto`.
+
+On a terminal, today's date is picked out in bold bright magenta. The highlight
+exists **only** in the coloured path: piped output is byte-for-byte
+identical whether or not today falls in the month shown, so nothing parsing
+stdout breaks on the one day a month it would otherwise appear. `--json`
+reports it as a `today` field instead, which is `null` when today is elsewhere.
+
+### Scripting
+
+Every command takes `--json`:
+
+```console
+$ nepkit ad2bs 2008-05-28 --json
+{"bs": "2065-02-15", "ad": "2008-05-28"}
+```
+
+**stdout carries results, stderr carries errors, and neither ever carries
+both.** stdout contains no ANSI escapes unless you ask for colour explicitly,
+so piping is always safe.
+
+Exit codes come straight from the exception hierarchy, so a script can branch
+without parsing any text:
+
+| Code | Meaning | Example |
+| --- | --- | --- |
+| 0 | success | |
+| 2 | usage error — bad flag or unknown command | `nepkit nosuchcommand` |
+| 3 | not a real date | `nepkit bs2ad 2081-13-01` |
+| 4 | a real date, but outside the bundled range | `nepkit bs2ad 2095-01-01` |
+
+The 3/4 split is the one that matters when scripting: **4 is worth retrying
+against another source, 3 never is.** Collapsing both into `1` would throw that
+distinction away at exactly the boundary where it is most useful.
+
+## Supported range
+
+| Calendar | From | To |
+| --- | --- | --- |
+| Bikram Sambat | 2000-01-01 | 2090-12-30 |
+| Gregorian | 1943-04-14 | 2034-04-13 |
+
+That is 91 years, 33,238 days. Anything outside it raises `DateOutOfRangeError`
+rather than extrapolating, because there is no rule to extrapolate with — dates
+beyond the table would have to be invented.
+
+The bounds are computed from the bundled data, not written down separately, so
+extending the table moves them automatically.
+
+## Design decisions
+
+**One anchor, everything else derived.** The whole library hangs on a single
+verified correspondence: BS 2000-01-01 = AD 1943-04-14. That is the only
+Gregorian fact in the package that cannot be computed, because month lengths
+alone cannot tell you where the calendar sits against the Gregorian one. Every
+other bound — the last BS date, both ends of the AD window — is derived from it
+plus the table. A second hardcoded date would be free to drift out of sync, and
+the failure would be silent and total.
+
+**Both directions collapse to a day count.** A BS date becomes "days since the
+anchor", integer arithmetic happens there, and the result expands out the other
+side. `datetime.date` is already a correct expander for the Gregorian side, so
+`bs_to_ad` is one line; the real work is the inverse, which has no equivalent in
+the standard library.
+
+**Types instead of validation where possible.** `ad_to_bs` accepts a
+`datetime.date` rather than three integers, which removes an entire error class
+from its contract at no cost.
+
+## Limitations
+
+- **Dates only.** No time of day, no timezones, no Nepali-language month names
+  or numeral formatting.
+- **The range is hard-bounded** at BS 2000–2090 and will not extrapolate.
+- **Correctness rests on the data, and the tests cannot prove it.** The test
+  suite verifies self-consistency exhaustively — every one of the 33,238 days
+  round-trips, and consecutive day counts produce consecutive dates. But both
+  directions read the same table, so a wrong month length cancels out exactly
+  and every property still passes. This was verified by deliberately corrupting
+  the table: all properties passed while conversions were silently wrong. Only
+  the sourcing described in [`src/nepkit/data/DATA.md`](https://github.com/akakritagya/nepkit/blob/main/src/nepkit/data/DATA.md)
+  stands behind the numbers themselves.
+
+## Data provenance
+
+[`src/nepkit/data/DATA.md`](https://github.com/akakritagya/nepkit/blob/main/src/nepkit/data/DATA.md) records where the calendar
+table came from: two independently maintained sources with different authors,
+languages, and conversion epochs, pinned at specific commits, diffed row by row
+over all 91 years with no disagreements, and cross-checked by walking each
+source forward from its own epoch to the anchor.
+
+## Development
+
+This project uses [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/akakritagya/nepkit
+cd nepkit
+uv sync --group dev          # pytest, ruff, mypy, pre-commit
+uv run pytest                # run tests
+uv run ruff check .          # lint
+uv run ruff format .         # format
+uv run mypy                  # type check
+```
+
+```bash
+uv run pre-commit install                         # lint/format/type-check on commit
+uv run pre-commit install --hook-type commit-msg  # enforce Conventional Commits
+uv run pre-commit install --hook-type pre-push    # full test suite before push
+```
+
+`pre-commit` runs lint, format, and type-check on every commit; blocks large
+files, private keys, and direct commits to `main`; runs the full `pytest` suite
+before `push` (not on every commit — too slow to survive contact with a growing
+suite); and enforces
+[Conventional Commits](https://www.conventionalcommits.org/) on the message.
+
+### Releasing
+
+Releases go to PyPI through
+[Trusted Publishing](https://docs.pypi.org/trusted-publishers/) — GitHub Actions
+proves the repository's identity over OIDC, so no API token exists to leak or
+rotate. Bump `version` in `pyproject.toml`, then:
+
+```bash
+git tag v0.1.0 && git push origin v0.1.0
+```
+
+The tag runs `.github/workflows/publish.yml`, which re-runs the full gate,
+refuses to continue if the tag disagrees with the packaged version, and only
+then uploads. Run the workflow manually to rehearse against TestPyPI first.
+
+## License
+
+MIT — see [LICENSE](https://github.com/akakritagya/nepkit/blob/main/LICENSE).

nepkit-0.1.0/README.md

@@ -0,0 +1,327 @@
+# nepkit
+
+```text
+                      _     _  _
+ _ __    ___   _ __  | | __(_)| |_
+| '_ \  / _ \ | '_ \ | |/ /| || __|
+| | | ||  __/ | |_) ||   < | || |_
+|_| |_| \___| | .__/ |_|\_\|_| \__|
+              |_|
+```
+
+Typed Bikram Sambat ↔ Gregorian date conversion for Python, as a library and a
+command-line tool.
+
+> **Status:** first release. The library and CLI both work and are tested; the
+> API may still change before 1.0.
+
+[**DEMO.md**](https://github.com/akakritagya/nepkit/blob/main/DEMO.md) walks
+through every command, option, and failure mode with real captured output.
+
+## Why
+
+Bikram Sambat is Nepal's official calendar, and converting to and from it is not
+arithmetic. Gregorian leap years follow a rule you can write down; BS month
+lengths do not. They vary between 29 and 32 days with no generating formula, are
+fixed by observation, and are published by Nepal's Panchanga authority. Every
+correct converter is therefore a **lookup table plus one verified anchor date** —
+which means the data matters more than the code, and most of the work in this
+repo went into the data.
+
+The existing Python options are small, mostly unmaintained packages with
+undocumented year ranges, no type hints, and no statement of where their numbers
+came from or how far they can be trusted. nepkit aims to be one typed, tested
+converter that is explicit about all three.
+
+## Install
+
+Requires Python 3.12+.
+
+```bash
+pip install nepkit       # library and CLI
+uv add nepkit            # into a uv project
+uv tool install nepkit   # the CLI on its own, isolated
+```
+
+[Typer](https://typer.tiangolo.com/) is the only direct dependency. The
+calendar table is bundled, so nepkit never touches the network.
+
+## Library
+
+```python
+from datetime import date
+
+from nepkit import BSDate, ad_to_bs, bs_to_ad
+
+bs_to_ad(BSDate(2081, 4, 15))  # date(2024, 7, 30)
+ad_to_bs(date(2024, 7, 30))  # BSDate(year=2081, month=4, day=15)
+```
+
+`BSDate` validates on construction, so if you are holding one it is a real date
+in the supported range:
+
+```python
+from nepkit import BSDate, days_in_month
+
+days_in_month(2081, 4)  # 32
+days_in_month(2081, 9)  # 29
+
+BSDate(2081, 4, 33)  # raises InvalidDateError
+BSDate(2081, 13, 1)  # raises InvalidDateError
+BSDate(2095, 1, 1)  # raises DateOutOfRangeError
+```
+
+`ad_to_bs` takes a `datetime.date`, so a malformed Gregorian date is impossible
+by construction — Python's own constructor rejects it before nepkit is involved.
+
+### Errors
+
+```text
+NepkitError
+├── CalendarDataError   the bundled table is malformed; raised at import
+└── DateError
+    ├── InvalidDateError      not a real BS date (month 13, day 33, ...)
+    └── DateOutOfRangeError   a real date, but outside the bundled range
+```
+
+The split between the last two is the one that earns its keep. BS 2095-03-12 is
+a perfectly real date that nepkit simply has no data for, and a caller can
+reasonably catch that and fall back or report the supported range. BS 2081-13-01
+is not a date at all, and catching it is always a mistake. Catch `DateError` if
+you only need "the user gave me something I can't convert".
+
+## CLI
+
+Installing puts a `nepkit` command on your PATH:
+
+```console
+$ nepkit bs2ad 2081-04-15
+2024-07-30
+
+$ nepkit ad2bs 2024-07-30
+2081-04-15
+
+$ nepkit today
+BS 2083-04-26
+AD 2026-08-11
+
+$ nepkit range
+BS 2000-01-01 .. 2090-12-30  (years 2000-2090)
+AD 1943-04-14 .. 2034-04-13
+```
+
+Direction is always explicit, and has to be: the BS and AD year numbers overlap
+from 2000 to 2034, so `2024` is a valid year in both calendars and nothing
+could reliably guess which one you meant.
+
+### Interactive
+
+Run `nepkit` with no arguments in a terminal and it clears the screen and opens
+a session:
+
+```console
+$ nepkit
+                      _     _  _
+ _ __    ___   _ __  | | __(_)| |_
+| '_ \  / _ \ | '_ \ | |/ /| || __|
+| | | ||  __/ | |_) ||   < | || |_
+|_| |_| \___| | .__/ |_|\_\|_| \__|
+              |_|
+nepkit v0.1.0 - Bikram Sambat (BS) <-> Gregorian (AD) date conversion
+Today  BS 2083-04-26   AD 2026-08-11
+
+Type a command, 'help', 'clear', or 'quit'.  Up/Down recalls history.
+
+nepkit> today
+BS 2083-04-26
+AD 2026-08-11
+
+nepkit> bs2ad 2081-04-15
+2024-07-30
+
+nepkit> quit
+```
+
+It accepts exactly the commands above — the same table, not a parallel
+interface — so anything you can type at the shell works here unchanged. A bad
+line reports the error and returns you to the prompt rather than ending the
+session. `clear` (or `cls`) wipes the screen and redraws the banner. `quit`,
+`exit`, `q`, and Ctrl-D all leave; Ctrl-C abandons the current line only.
+
+Those four are prompt-only words, not subcommands — `nepkit clear` at a shell
+stays a usage error rather than clearing your terminal.
+
+Up and Down recall previous commands, and the usual `readline` editing keys
+work (Ctrl-A, Ctrl-E, Ctrl-R, and so on). History lasts for the session and is
+not written to disk. On Windows, where Python ships no `readline`, the prompt
+works exactly the same minus the editing keys.
+
+**Only on a terminal.** With stdin redirected — a pipeline, a script, CI —
+`nepkit` prints help and exits 2 exactly as before, so nothing ever blocks
+waiting for a prompt that isn't there.
+
+### Calendars
+
+```console
+$ nepkit calbs 2081 4
+        Shrawan 2081
+    16 Jul - 16 Aug 2024
+Sun Mon Tue Wed Thu Fri Sat
+          1   2   3   4   5
+  6   7   8   9  10  11  12
+ 13  14  15  16  17  18  19
+ 20  21  22  23  24  25  26
+ 27  28  29  30  31  32
+
+$ nepkit calad 2024 7
+         July 2024
+Ashadh 17 - Shrawan 16, 2081
+Sun Mon Tue Wed Thu Fri Sat
+      1   2   3   4   5   6
+  7   8   9  10  11  12  13
+ 14  15  16  17  18  19  20
+ 21  22  23  24  25  26  27
+ 28  29  30  31
+```
+
+Both default to the current month. A Gregorian month never lines up with a BS
+month, so the subtitle names both ends of the span rather than pretending a
+single corresponding month exists.
+
+Grids are boxed and coloured on a terminal and plain when redirected, following
+the same convention as `ls` and `git`. Force it either way with
+`--color always|never|auto`.
+
+On a terminal, today's date is picked out in bold bright magenta. The highlight
+exists **only** in the coloured path: piped output is byte-for-byte
+identical whether or not today falls in the month shown, so nothing parsing
+stdout breaks on the one day a month it would otherwise appear. `--json`
+reports it as a `today` field instead, which is `null` when today is elsewhere.
+
+### Scripting
+
+Every command takes `--json`:
+
+```console
+$ nepkit ad2bs 2008-05-28 --json
+{"bs": "2065-02-15", "ad": "2008-05-28"}
+```
+
+**stdout carries results, stderr carries errors, and neither ever carries
+both.** stdout contains no ANSI escapes unless you ask for colour explicitly,
+so piping is always safe.
+
+Exit codes come straight from the exception hierarchy, so a script can branch
+without parsing any text:
+
+| Code | Meaning | Example |
+| --- | --- | --- |
+| 0 | success | |
+| 2 | usage error — bad flag or unknown command | `nepkit nosuchcommand` |
+| 3 | not a real date | `nepkit bs2ad 2081-13-01` |
+| 4 | a real date, but outside the bundled range | `nepkit bs2ad 2095-01-01` |
+
+The 3/4 split is the one that matters when scripting: **4 is worth retrying
+against another source, 3 never is.** Collapsing both into `1` would throw that
+distinction away at exactly the boundary where it is most useful.
+
+## Supported range
+
+| Calendar | From | To |
+| --- | --- | --- |
+| Bikram Sambat | 2000-01-01 | 2090-12-30 |
+| Gregorian | 1943-04-14 | 2034-04-13 |
+
+That is 91 years, 33,238 days. Anything outside it raises `DateOutOfRangeError`
+rather than extrapolating, because there is no rule to extrapolate with — dates
+beyond the table would have to be invented.
+
+The bounds are computed from the bundled data, not written down separately, so
+extending the table moves them automatically.
+
+## Design decisions
+
+**One anchor, everything else derived.** The whole library hangs on a single
+verified correspondence: BS 2000-01-01 = AD 1943-04-14. That is the only
+Gregorian fact in the package that cannot be computed, because month lengths
+alone cannot tell you where the calendar sits against the Gregorian one. Every
+other bound — the last BS date, both ends of the AD window — is derived from it
+plus the table. A second hardcoded date would be free to drift out of sync, and
+the failure would be silent and total.
+
+**Both directions collapse to a day count.** A BS date becomes "days since the
+anchor", integer arithmetic happens there, and the result expands out the other
+side. `datetime.date` is already a correct expander for the Gregorian side, so
+`bs_to_ad` is one line; the real work is the inverse, which has no equivalent in
+the standard library.
+
+**Types instead of validation where possible.** `ad_to_bs` accepts a
+`datetime.date` rather than three integers, which removes an entire error class
+from its contract at no cost.
+
+## Limitations
+
+- **Dates only.** No time of day, no timezones, no Nepali-language month names
+  or numeral formatting.
+- **The range is hard-bounded** at BS 2000–2090 and will not extrapolate.
+- **Correctness rests on the data, and the tests cannot prove it.** The test
+  suite verifies self-consistency exhaustively — every one of the 33,238 days
+  round-trips, and consecutive day counts produce consecutive dates. But both
+  directions read the same table, so a wrong month length cancels out exactly
+  and every property still passes. This was verified by deliberately corrupting
+  the table: all properties passed while conversions were silently wrong. Only
+  the sourcing described in [`src/nepkit/data/DATA.md`](https://github.com/akakritagya/nepkit/blob/main/src/nepkit/data/DATA.md)
+  stands behind the numbers themselves.
+
+## Data provenance
+
+[`src/nepkit/data/DATA.md`](https://github.com/akakritagya/nepkit/blob/main/src/nepkit/data/DATA.md) records where the calendar
+table came from: two independently maintained sources with different authors,
+languages, and conversion epochs, pinned at specific commits, diffed row by row
+over all 91 years with no disagreements, and cross-checked by walking each
+source forward from its own epoch to the anchor.
+
+## Development
+
+This project uses [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/akakritagya/nepkit
+cd nepkit
+uv sync --group dev          # pytest, ruff, mypy, pre-commit
+uv run pytest                # run tests
+uv run ruff check .          # lint
+uv run ruff format .         # format
+uv run mypy                  # type check
+```
+
+```bash
+uv run pre-commit install                         # lint/format/type-check on commit
+uv run pre-commit install --hook-type commit-msg  # enforce Conventional Commits
+uv run pre-commit install --hook-type pre-push    # full test suite before push
+```
+
+`pre-commit` runs lint, format, and type-check on every commit; blocks large
+files, private keys, and direct commits to `main`; runs the full `pytest` suite
+before `push` (not on every commit — too slow to survive contact with a growing
+suite); and enforces
+[Conventional Commits](https://www.conventionalcommits.org/) on the message.
+
+### Releasing
+
+Releases go to PyPI through
+[Trusted Publishing](https://docs.pypi.org/trusted-publishers/) — GitHub Actions
+proves the repository's identity over OIDC, so no API token exists to leak or
+rotate. Bump `version` in `pyproject.toml`, then:
+
+```bash
+git tag v0.1.0 && git push origin v0.1.0
+```
+
+The tag runs `.github/workflows/publish.yml`, which re-runs the full gate,
+refuses to continue if the tag disagrees with the packaged version, and only
+then uploads. Run the workflow manually to rehearse against TestPyPI first.
+
+## License
+
+MIT — see [LICENSE](https://github.com/akakritagya/nepkit/blob/main/LICENSE).