Merge remote-tracking branch 'origin/main'

Author: alexeygrigorev

.github/workflows/typefully-analyzer.yml

@@ -1,75 +1,46 @@
-# Typefully Export Scripts
+# Manual Typefully Exporter
 
-Utilities for exporting Typefully social-set drafts and turning them into local
-analysis/process-doc drafts.
+`export-posts.mjs` is retained as manual, one-shot raw source-export tooling.
+It is not a supported product feature and must not run from application
+runtime, deployment, CI, tests, schedules, or other recurring automation.
 
-The exporter reads `TYPEFULLY_API_KEY` from `.env` or the environment and does
-not print the token. The analyzer reads only its caller-supplied local JSON file
-and makes no credential or network request. Keep exports under `.tmp/` because
-post archives can contain private Typefully URLs, draft text, and unpublished
-drafts.
+Running the exporter requires explicit HUMAN authorization for both provider
+access and the intended export scope. The operator must supply an authorized
+`TYPEFULLY_API_KEY` through the environment or the repository's ignored
+`.env` file. The script does not print the token.
 
-Generated analysis and process-document drafts are also private operational
-data and stay under ignored `.tmp/` paths until separately reviewed for
-promotion. The analyzer omits provider private, share, and edit link metadata
-from every generated file. If the same exact private link value appears inside
-otherwise useful post evidence, it is replaced with a fixed neutral omission
-marker. Wrapper punctuation does not suppress omission, while a distinct,
-syntactically valid longer public URL remains unchanged.
+Raw exports can contain unpublished text, account context, provider metadata,
+and private Typefully links. Always write them below the repository's ignored
+`.tmp/` directory; they must never be committed, uploaded as public CI
+artifacts, or treated as durable operational knowledge.
 
-## Export drafts and posts
+After an authorized export, review, analysis, curation, retention, and disposal
+belong to the private operational-knowledge process. Do not add raw exports or
+derived operational documents to this public repository.
 
-```bash
-node scripts/typefully/export-posts.mjs \
-  --output .tmp/typefully-export \
-  --status all
-```
-
-By default, the exporter discovers all Typefully social sets available to the
-API key. To restrict the export, pass one or more social-set names, usernames,
-or ids:
-
-```bash
-node scripts/typefully/export-posts.mjs \
-  --output .tmp/typefully-export \
-  --status published \
-  --social-set DataTalksClub \
-  --social-set Al_Grigor
-```
-
-The export includes:
-
-- `social-sets.json`: accessible social sets and connected platforms.
-- `<social-set>-drafts.json`: raw draft list and detail responses.
-- `all-drafts.json`: combined raw export.
-- `posts.jsonl`: one normalized row per platform post.
-- `posts.csv`: same normalized rows for spreadsheet analysis.
-
-The normalized rows include both X/Twitter (`platform=x`) and LinkedIn
-(`platform=linkedin`) posts when present in Typefully draft details.
+## Authorized manual use
 
-## Optional X analytics samples
-
-Typefully analytics currently supports X posts only. LinkedIn analytics is not
-available through the Typefully endpoint tested on 2026-06-29.
+The exporter discovers every social set available to the API key unless the
+operator restricts the scope with one or more `--social-set` selectors. Prefer
+an explicit scope and status approved for the one-shot operation:
 
 ```bash
 node scripts/typefully/export-posts.mjs \
   --output .tmp/typefully-export \
   --status published \
-  --include-x-analytics \
-  --analytics-start-year 2022
+  --social-set <approved-name-username-or-id>
 ```
 
-## Analyze an export
-
-```bash
-node scripts/typefully/analyze-posts.mjs \
-  --input .tmp/typefully-export/all-drafts.json \
-  --output .tmp/typefully-analysis
-```
+The ignored output can include:
 
-This creates:
+- `social-sets.json`, containing accessible social sets and platforms;
+- `<social-set>-drafts.json`, containing raw draft records and details;
+- `all-drafts.json`, containing the combined raw export;
+- `posts.jsonl` and `posts.csv`, containing normalized platform-post rows; and
+- `x-analytics.json` when the separately authorized
+  `--include-x-analytics` option is used.
 
-- `analysis.md`
-- `process-doc-drafts/*.md`
+Use `node scripts/typefully/export-posts.mjs --help` to inspect the available
+manual options before an authorized run. A past export does not authorize a
+future one; each run requires a new HUMAN/provider authorization and an
+explicit private-data disposition.