1 files changed, 85 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ded0877
--- /dev/null
+++ b/README.md
@@ -0,0 +1,85 @@
+# slackware-changelog
+
+Shows the latest [Slackware -current](https://mirrors.slackware.com/slackware/slackware64-current/ChangeLog.txt)
+ChangeLog entry: date, how many packages moved, and how many carry a security
+fix.
+
+Homepage's `customapi` widget speaks JSON only, and the ChangeLog is plain
+text: several thousand lines covering years of entries, of which only the
+first block is wanted. This proxy fetches it, parses the latest entry, caches
+it so the widget refresh does not hit the mirror, and serves the fields.
+
+Stdlib Python, no dependencies, one file.
+
+## Features
+
+- Counts per action: upgraded, rebuilt, added, removed
+- Security fixes counted, and the CVE ids of the entry collected
+- The full entry as a readable page, linked from the card
+- A second card listing the packages themselves, truncated with a "... and N more" row
+- An unreachable mirror serves the last good entry, flagged as stale, rather than a blank card
+
+## Endpoints
+
+| Path | Returns |
+|---|---|
+| `/latest` (or `/`) | Date, counts, one-line summary, CVE ids |
+| `/top` | The first `TOP_N` packages as flat `pkg1..pkgN` fields, plus an overflow row. `?n=` overrides |
+| `/packages` | Every package in the entry, with its action |
+| `/entry` | The full entry as HTML |
+| `/refresh` | Same as `/latest`, ignoring the cache |
+
+## Install
+
+Runs on the machine hosting Homepage, listening on `127.0.0.1:8098`.
+
+```bash
+install -Dm755 slackware_changelog.py /opt/slackware-changelog/slackware_changelog.py
+install -Dm644 slackware-changelog.service /etc/systemd/system/slackware-changelog.service
+# edit the unit if you want a nearer mirror
+systemctl daemon-reload && systemctl enable --now slackware-changelog
+curl -s localhost:8098/latest
+```
+
+Then merge `homepage-services.yaml` into Homepage's `services.yaml` and the
+`layout:` block from `homepage-settings.yaml` into its `settings.yaml`, and
+restart Homepage.
+
+## Configuration
+
+Environment variables, set in the unit file:
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `CHANGELOG_URL` | `https://mirrors.slackware.com/.../slackware64-current/ChangeLog.txt` | Use a nearer mirror, or `slackware-current` for 32-bit |
+| `PORT` | `8098` | Listen port, bound to localhost |
+| `CACHE_TTL` | `1800` | Seconds before the mirror is fetched again |
+| `TOP_N` | `8` | Packages listed by `/top` before it truncates |
+
+## Parsing
+
+An entry runs from the top of the file to the first `+----+` separator line.
+Inside it, a package line starts at column 0 and reads `path/name.txz:  Action.`;
+indented lines below it are free-text notes, which is why the parser anchors
+on the column and not on the trailing period. Notes are kept in the entry text
+but never counted as packages.
+
+## Tests
+
+```bash
+python3 test_changelog.py
+```
+
+Fakes the mirror, so it needs no network. Prints `ok`.
+
+## License
+
+GPLv2. See [LICENSE](LICENSE).
+
+## Development Approach
+
+This project is developed using AI-assisted tools. Code is generated with the help of AI based on human-provided specifications, design decisions, and iterative feedback.
+
+All contributions are reviewed, tested, and curated by the maintainer before being included in the codebase. AI is used as a productivity and exploration tool, while human oversight remains central to all decisions.
+
+The goal is to combine the flexibility of AI-assisted development with standard open-source practices such as transparency, review, and accountability.