feat: add ownership snapshot publish flow

docs/OWNERSHIP_PUBLISH.md

@@ -0,0 +1,95 @@
+# Ownership Snapshot Publishing
+
+This document covers the maintainer workflow for producing and publishing the
+ownership snapshot artifacts consumed by `idx ownership sync`.
+
+## Goals
+
+- Build the snapshot from the currently discoverable supported IDX/KSEI source,
+  not from an ad hoc local DB.
+- Keep the published manifest URL stable for end users.
+- Record source provenance in the manifest so the published SQLite artifact can
+  be traced back to the live IDX announcement and PDF URL used to build it.
+
+## Recommended GitHub Releases Layout
+
+Use a dedicated stable release tag for snapshot assets:
+
+- tag: `ownership-snapshot-current`
+- manifest asset: `ownership-snapshot-manifest.json`
+- SQLite asset: `ownership-snapshot-YYYY-MM-DD.sqlite`
+
+Recommended public manifest URL:
+
+```text
+https://github.com/0xrsydn/idx-cli/releases/download/ownership-snapshot-current/ownership-snapshot-manifest.json
+```
+
+Avoid `.../releases/latest/download/...` if normal app releases and snapshot
+publishes share the same repository. The repo's "latest" release can drift away
+from the ownership snapshot release.
+
+## Manual Maintainer Flow
+
+Run the publisher helper inside `nix develop` so `mutool` and the
+`curl-impersonate` helper are available:
+
+```bash
+nix develop --command cargo build
+nix develop --command scripts/build-latest-ownership-snapshot.sh \
+  --idx-bin ./target/debug/idx \
+  --output-dir dist/ownership-snapshot \
+  --repo 0xrsydn/idx-cli \
+  --release-tag ownership-snapshot-current
+```
+
+The script performs these steps:
+
+1. `idx -o json ownership discover --family above1 --limit 1`
+2. verifies the discovered report is the current supported import path
+3. imports that PDF into an isolated temp ownership DB
+4. checks that the imported release metadata is non-empty and tied to the same
+   source URL
+5. runs `scripts/build-ownership-snapshot.sh` to emit the SQLite artifact and
+   base manifest
+6. enriches the manifest with `source` provenance metadata
+
+The resulting manifest records:
+
+- `source.family`
+- `source.listing_page_url`
+- `source.query_url`
+- `source.pdf_url`
+- `source.title`
+- `source.publish_date`
+- `source.original_filename`
+
+That metadata is additive. Existing sync clients can still parse the manifest.
+
+## Upload Step
+
+After the local build succeeds, upload these two files to the
+`ownership-snapshot-current` GitHub release:
+
+- `dist/ownership-snapshot/ownership-snapshot-manifest.json`
+- `dist/ownership-snapshot/ownership-snapshot-YYYY-MM-DD.sqlite`
+
+Only after this manual flow is reliable should the repo automate it in
+GitHub Actions.
+
+## GitHub Actions Workflow
+
+The repo now includes a manual workflow at
+`.github/workflows/publish-ownership-snapshot.yml`.
+
+Current behavior:
+
+- trigger: `workflow_dispatch` only
+- builds `idx` inside `nix develop`
+- runs `scripts/build-latest-ownership-snapshot.sh`
+- uploads the generated files as workflow artifacts
+- creates the stable release tag if needed
+- uploads the manifest and SQLite asset to that release with `--clobber`
+
+This is intentionally manual-first. Add a schedule only after a few successful
+publish runs confirm the live source remains stable enough.

docs/OWNERSHIP_SYNC.md

@@ -4,6 +4,9 @@
 
 The command is intentionally manifest-driven so the repo can publish snapshots in GitHub releases, object storage, or a local filesystem path without changing the CLI.
 
+The recommended GitHub publish layout and maintainer workflow are documented in
+`docs/OWNERSHIP_PUBLISH.md`.
+
 ## Consumer Inputs
 
 The manifest location is resolved in this order:
@@ -24,6 +27,15 @@ Current schema version: `1`
 {
   "schema_version": 1,
   "generated_at": "2026-03-31T12:00:00Z",
+  "source": {
+    "family": "above1",
+    "listing_page_url": "https://www.idx.co.id/id/berita/pengumuman/",
+    "query_url": "https://www.idx.co.id/primary/NewsAnnouncement/GetAllAnnouncement?...",
+    "pdf_url": "https://www.idx.co.id/StaticData/NewsAndAnnouncement/...pdf",
+    "title": "Pemegang Saham di atas 1% (KSEI)",
+    "publish_date": "2026-03-10T00:00:00",
+    "original_filename": "b9b638e5a8_8928aca255.pdf"
+  },
   "snapshot": {
     "kind": "sqlite",
     "compression": "none",
@@ -41,6 +53,7 @@ Current schema version: `1`
 ```
 
 Semantics:
+- `source` is optional provenance metadata describing the IDX/KSEI PDF used to build the snapshot.
 - `download_url` points to the SQLite artifact itself.
 - `sqlite_sha256` and `size_bytes` are validated before install.
 - `latest_*` and `release_count` are validated against the downloaded SQLite contents before replacement.
@@ -71,3 +84,7 @@ scripts/build-ownership-snapshot.sh \
 ```
 
 If `--base-url` is omitted, the generated manifest uses the local artifact path as `download_url`, which is useful for local testing.
+
+For the maintainer flow that discovers the latest supported IDX/KSEI source
+first and then builds GitHub-release-ready assets, use
+`scripts/build-latest-ownership-snapshot.sh`.