feat: official Follow Intent and audience insights (#4)

* chore(manifest): define audience API contracts

* feat(core): add audience domain contracts

* feat(cli): add official follow intent

* fix(auth): harden audience reauthorization

* feat(provider): add official audience endpoints

* feat(store): persist audience snapshots

* feat(store): rank observed engagement

* feat(ingest): refresh audience data

* feat(cli): render audience reports

* feat(cli): add audience commands

* test(cli): cover audience workflows end to end

* docs: document audience and follow support

* refactor(core): split model into domain modules and add demographic insight

* refactor(store): split query module and harden private file I/O

* refactor(provider): split client and provider modules; correct DTOs, paths, and retry

* fix(auth): harden token store, config, and local secret handling

* refactor(ingest): split orchestrator and correct audience refresh

* fix(cli): correct audience output and recovery; update tests and docs

* fix(store): exclude quote posts from engagement ranking

* fix(auth): add oauth endpoint seams and guide insights permission denial

* test(ingest): assert repeated audience refresh is idempotent

* fix(provider): forward client-selected mentions page size and correct docs

* fix(auth): gate oauth endpoint injection behind test-support

* fix(core): map permission denials to typed permission requirements

Author: chrisgeo

Cargo.lock

@@ -47,6 +47,7 @@ csv = "1.3"
 
 # cli
 clap = { version = "4.5", features = ["derive", "env", "wrap_help"] }
+open = "5"
 
 # storage
 rusqlite = { version = "0.33", features = ["bundled", "chrono", "serde_json"] }
@@ -64,6 +65,7 @@ keyring = { version = "3", default-features = false, features = [
   "sync-secret-service",
 ] }
 dirs = "5"
+libc = "0.2"
 
 # test helpers
 tempfile = "3"

Cargo.toml

@@ -12,7 +12,9 @@ A Rust CLI for ingesting, modeling, searching, and exporting
 
 ## Status
 
-Phase 0 foundation scaffolding. See
+Audience snapshots, observed-engagement queries, and the official Follow
+Intent command are implemented. Private follower enumeration and automated
+follow remain unsupported. See
 [`docs/architecture.md`](docs/architecture.md) and
 [`threads_api_cli_prd_correction.md`](threads_api_cli_prd_correction.md).
 
@@ -37,9 +39,17 @@ cargo build --workspace
 cargo test  --workspace
 ```
 
+## Token persistence
+
+`auth login` always atomically mirrors the access token and its metadata to a
+private token file, then saves the same value to Keychain on a best-effort
+basis. Reads are file-first; Keychain is consulted only when the private file
+is absent. On Unix, the file is accepted only when it is an owner-only regular
+file in an owner-controlled directory that is not group- or world-writable.
+
 ## Commands
 
-Read-only ingest + query (always safe):
+Local ingest/query and user-mediated intent commands:
 
 ```
 threads-cli init
@@ -48,8 +58,43 @@ threads-cli ingest me | thread <post_id> | engagement [--depth N]
 threads-cli show <post_id> [--thread]
 threads-cli search "<query>"
 threads-cli export --format json|jsonl|csv
+threads-cli follow <username> [--no-open]
+threads-cli audience refresh
+threads-cli audience show [--history N]
+threads-cli audience engaged [--limit N] [--sort total|replies|mentions]
+threads-cli audience purge --before <date> [--apply]
 ```
 
+`follow` prints and optionally opens Meta's official Follow Intent. It does
+not perform or confirm a follow. `audience refresh` fetches aggregate
+`followers_count`, eligible country/city/age/gender demographics, and
+official public mentions. `show`, `engaged`, and `purge` are local and use the
+token-bound account. Engagement is based on observed direct replies and
+mentions, not a follower list; engaged accounts must never be interpreted as
+followers. Audience snapshots are private local data, excluded from post
+export, and explicitly removable with `audience purge`.
+
+Audience defaults: `show --history 10`, `engaged --limit 20 --sort total`.
+`purge` is a dry run unless `--apply` is supplied. `refresh` requires the
+recorded `threads_manage_insights` and `threads_manage_mentions` scopes.
+The broad login requests exactly these six scopes:
+`threads_basic`, `threads_read_replies`, `threads_delete`,
+`threads_content_publish`, `threads_manage_insights`, and
+`threads_manage_mentions`. Requested scopes are not proof that Meta granted
+them; App Review and the user grant control access. The Mentions live gate is
+EXTERNALLY UNVERIFIED.
+
+Mentions uses Meta's cursor pagination. `audience refresh` selects 100 items
+per page as this client's implementation choice; it is not an asserted Meta
+maximum.
+
+After the Insights snapshot is committed, only a Mentions permission denial is
+downgraded to a warning. That warning names the required
+`threads_manage_mentions` scope and recommends `threads-cli auth login` to
+request it again. Other Mentions-phase errors (authentication, network, parse,
+rate-limit, or store failures) fail `audience refresh`; the already committed
+Insights snapshot remains available locally.
+
 Destructive remote ops (dry-run by default; `--apply` actually performs the
 delete via Meta's `DELETE /v1.0/{id}` endpoint):
 
@@ -65,9 +110,11 @@ accept either RFC 3339 (`2025-01-15T00:00:00Z`) or bare ISO date
 quota will reset. See [`docs/plans/delete.md`](docs/plans/delete.md) for the
 full design.
 
-Publishing (`threads_publish`), `archive` (Meta does not expose a remote
-archive endpoint for root posts), multi-account, and the private
-`threads.net/api/graphql` adapter are deferred past v1.
+Publishing is supported. `archive` (Meta does not expose a remote archive
+endpoint for root posts), multi-account, and the private
+`threads.net/api/graphql` adapter remain outside the supported v1 surface.
+The web adapter is disabled by default and read-only; it must not be used for
+follower enumeration or automated follow actions.
 
 ## License
 

README.md

@@ -22,6 +22,9 @@ chrono.workspace = true
 clap.workspace = true
 csv.workspace = true
 dirs.workspace = true
+libc = "0.2"
+open.workspace = true
+rand = { version = "0.10", default-features = false, features = ["std", "std_rng", "sys_rng"] }
 serde.workspace = true
 serde_json.workspace = true
 toml.workspace = true
@@ -33,3 +36,4 @@ url.workspace = true
 [dev-dependencies]
 async-trait.workspace = true
 tempfile.workspace = true
+threads-provider-official = { workspace = true, features = ["test-support"] }