Harden snapshot policy and private publication

Author: mohsinht

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 All notable changes follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and semantic versioning.
 
-## [0.1.1] - 2026-08-24
+## [0.1.1] - Unreleased
 
 ### Added
 

README.md

@@ -24,14 +24,15 @@ You choose the LLM. You own the data. You control the deployment. Zaati OS has n
     ·  
   <a href="docs/quickstart.md">Quickstart</a>
   &nbsp;&nbsp;·&nbsp;&nbsp;
-  <a href="https://mohsinht.github.io/zaati-os/">Live synthetic demo</a>
-  &nbsp;&nbsp;·&nbsp;&nbsp;
   <a href="docs/privacy.md">Privacy model</a>
 </p>
 
 > [!IMPORTANT]
 > Zaati OS supplies contracts, prompts, validators, storage, rendering, and deployment infrastructure. It does not ship built-in Gmail, Jira, calendar, or financial connectors. Your chosen LLM or workflow must already have approved, read-only access to each source.
 
+> [!NOTE]
+> The Zaati dashboard is read-only. It displays validated snapshots and safe external links. It does not reply to messages, change calendars or tasks, send notifications, trade, or write back to source systems. The maintained production recipe is for developers and technical AI power users.
+
 ## What makes it different
 
 - **Any LLM workflow:** ChatGPT, Claude, Gemini, a local model, n8n, cron, or custom code can publish the same contract.
@@ -74,7 +75,7 @@ make tutorial
 
 Everything else, including custom sources, encrypted storage, full theme tokens, and automatic deployment, is optional and documented separately.
 
-The shortest useful loop is three sources, for example agenda, inbox attention, and work focus, followed by the daily overview prompt.
+The canonical daily bundle contains agenda, inbox attention, work focus, money, news, and the dependency-backed daily overview. Prompt Studio can also create smaller independent bundles, and now generates the matching private-repository setup command.
 
 ## Create a scheduled task prompt
 
@@ -107,7 +108,7 @@ No upstream Zaati OS service participates in this flow.
 
 ## One run, many snapshots
 
-`schemas/snapshot-bundle.schema.json` lets one LLM run produce up to 20 registered snapshots. Zaati OS compares the returned sources with the workflow's authoritative source set, sends concise contract errors back for up to three attempts, and writes nothing until every nested snapshot passes. Git publication uses one pull request whose independent validator must pass before a human or trusted merge policy accepts it.
+`schemas/snapshot-bundle.schema.json` lets one LLM run produce up to 20 registered snapshots. Zaati OS compares the returned sources with the workflow's authoritative source set, applies one shared privacy and temporal policy, sends concise contract errors back for up to three attempts, and writes nothing to its local snapshot store until every nested snapshot passes. Git publication creates candidate files on a private branch before CI; the independent validator prevents invalid candidates from merging into the protected data branch.
 
 This is especially useful for scheduled AI products where active task capacity is limited. One daily task can refresh agenda, inbox, work, money, news, and the overview instead of consuming one task per source. Start with the [one-task tutorial](docs/tutorials/one-task-daily-bundle.md).
 
@@ -154,7 +155,7 @@ See [LLM contract](docs/llm-contract.md) and [`schemas/`](schemas/) for the exec
 | `daily-overview.md`  | Combine registered source snapshots                  | Adaptive dashboard            |
 | `weekly-review.md`   | Find patterns and produce an evidence-based review   | Progress, timeline, decisions |
 
-These are provider-neutral templates, not connectors. The ChatGPT scheduled-task recipe is the maintained first path. Other providers are contract-compatible but are not claimed as end-to-end certified until their documented release gate passes.
+These are provider-neutral templates, not connectors. ChatGPT scheduled tasks are the target first real path, but the release evidence is not complete yet. Other providers are contract-compatible and are not claimed as end-to-end certified until their documented release gate passes.
 
 ## Repository map
 
@@ -174,7 +175,7 @@ deployments/           Optional infrastructure recipes
 
 ## Privacy model
 
-A public fork is code, not a diary. Real snapshots, instance configuration, connector exports, secrets, and generated dashboard data are ignored. CI rejects committed private snapshot paths and common secret shapes. Synthetic examples are visibly marked and schema-validated.
+A public fork is code, not a diary. Real snapshots, instance configuration, connector exports, secrets, and generated dashboard data are ignored. CI rejects committed private snapshot paths and common credential shapes. This scanner is defense in depth, not a promise to recognize every secret or unnecessary personal detail. Synthetic examples are visibly marked and schema-validated.
 
 Optional AES-256-GCM snapshot encryption protects files at rest with a key supplied only through an ignored local key file or protected CI secret. It is feature flagged and off by default. Use it only with a trusted ingestion process that can receive the key. Never paste the key into an LLM prompt. Encryption does not replace Access because authorized builds and browsers must eventually decrypt displayed facts.
 
@@ -226,16 +227,16 @@ Pull requests expose each gate as a separate job and finish with one `Quality ga
 ![Animated terminal showing Cloudflare Access verification](docs/assets/onboarding/deploy.gif)
 
 - **Recommended:** Cloudflare Workers static assets on a custom domain protected by Cloudflare Access.
-- **Supported:** Any private static host that provides real authentication before serving assets.
+- **Portable, community-operated:** Any private static host that provides real authentication before serving assets. Cloudflare is the only maintained security-complete recipe in v0.1.1.
 - **Not recommended for real data:** Public GitHub Pages, unauthenticated preview URLs, or relying on an obscure URL.
 
 Zaati OS charges no platform fee and can be deployed using free or already-owned tools, depending on provider, connector, model, storage, and hosting choices.
 
 ## Release
 
-Current version: **v0.1.1**
+Code version: **v0.1.1**
 
-This release establishes the portable data contract, atomic bundle ingestion, adaptive renderer, guided onboarding, provider-neutral prompts, optional encrypted storage, theme studio, privacy boundaries, Cloudflare recipe, and CI quality gates. See [CHANGELOG.md](CHANGELOG.md).
+No immutable GitHub Release is published yet. Until the recorded provider and hosted-demo release gates pass, pin private validators to a reviewed full commit SHA. This code version establishes the portable data contract, atomic bundle ingestion, adaptive renderer, guided onboarding, provider-neutral prompts, optional encrypted storage, theme studio, privacy boundaries, Cloudflare recipe, and CI quality gates. See [CHANGELOG.md](CHANGELOG.md).
 
 Before storing real data, read [Data lifecycle and key recovery](docs/data-lifecycle.md). Fork maintainers can follow [Upgrade and fork sync](docs/upgrading.md).
 

SUPPORT.md

@@ -1,6 +1,6 @@
 # Support
 
-Use GitHub Discussions for setup help and design ideas. Use GitHub Issues for reproducible bugs with synthetic examples only. Report vulnerabilities privately through the process in `SECURITY.md`.
+Use GitHub Issues for setup help, design ideas, and reproducible bugs with synthetic examples only. Report vulnerabilities privately through the process in `SECURITY.md`.
 
 Never post snapshot files, provider exports, repository tokens, decryption keys, private deployment URLs, account identifiers, or screenshots containing real personal data. Maintainers should be able to reproduce every report with the synthetic tutorial.
 

data/examples/money/pulse/2026-08-24.json

@@ -5,14 +5,14 @@
   "source_id": "money:pulse",
   "domain": "money",
   "source": "pulse",
-  "generated_at": "2026-08-23T18:00:00Z",
-  "effective_period": { "start": "2026-08-23T00:00:00Z", "end": "2026-08-23T23:59:59Z", "timezone": "UTC" },
+  "generated_at": "2026-08-24T07:00:00Z",
+  "effective_period": { "start": "2026-08-23T07:00:00Z", "end": "2026-08-24T07:00:00Z", "timezone": "UTC" },
   "status": "partial",
   "producer": { "worker_id": "money-pulse-daily", "workflow": "example", "version": "0.1.1" },
   "sources": [
     { "label": "Synthetic account summary", "status": "stale", "as_of": "2026-08-23T18:00:00Z", "reference": "synthetic://money" }
   ],
-  "freshness": { "expires_at": "2026-08-25T06:00:00Z" },
+  "freshness": { "expires_at": "2026-08-25T19:00:00Z" },
   "quality": { "confidence": "medium", "warnings": ["One synthetic source has not refreshed today."] },
   "privacy": { "classification": "public", "contains_personal_data": false, "synthetic": true },
   "data": {

docs/compatibility.md

@@ -2,11 +2,11 @@
 
 The JSON contract is provider-neutral. End-to-end support is a stronger claim.
 
-| Path                                   | v0.1.1 status                  | Required release evidence                                                   |
-| -------------------------------------- | ------------------------------ | --------------------------------------------------------------------------- |
-| Local mock tutorial                    | Maintained                     | Retry, atomicity, accessibility, and build tests in CI                      |
-| ChatGPT scheduled task                 | Maintained first real workflow | Prompt generation, permission receipt, pull request, independent validation |
-| Command adapter                        | Maintained                     | Exact JSON on stdout and trusted local validation                           |
-| Claude, Gemini, other hosted workflows | Contract compatible            | Community recipe until its complete path has a repeatable release test      |
+| Path                                   | v0.1.1 status              | Required release evidence                                              |
+| -------------------------------------- | -------------------------- | ---------------------------------------------------------------------- |
+| Local mock tutorial                    | Maintained                 | Retry, atomicity, accessibility, and build tests in CI                 |
+| ChatGPT scheduled task                 | Target first real workflow | A recorded synthetic provider run is still required before release     |
+| Command adapter                        | Maintained                 | Exact JSON on stdout and trusted local validation                      |
+| Claude, Gemini, other hosted workflows | Contract compatible        | Community recipe until its complete path has a repeatable release test |
 
 Zaati OS does not bundle provider connectors. Availability, permissions, retention, pricing, and scheduled-task behavior belong to the chosen provider.

docs/deployment/data-repository.md

@@ -24,7 +24,7 @@ The public source catalog and schemas remain in the code repository. Workers rea
 
 Use separate, least-privilege identities:
 
-- The LLM workflow needs permission to create a branch and pull request only in the private data repository. Prefer its existing GitHub connection instead of putting a token inside the prompt.
+- The LLM workflow needs only **Contents: read and write** plus **Pull requests: read and write** in the private data repository. Explicitly deny Actions, Workflows, Administration, repository settings, environments, secrets, and variables write access. Prefer a narrowly configured GitHub App or fine-grained credential instead of putting a token inside the prompt.
 - The deployment workflow needs a fine-grained token restricted to this one private repository with Contents read permission.
 - Cloudflare credentials never belong in the data repository.
 
@@ -40,11 +40,19 @@ npm run data-repository:init -- --repository-root ../zaati-data --code-repositor
 
 Commit the generated `zaati.data.json` and workflow, then require `Validate Zaati snapshots` in branch protection. Use an immutable 40-character commit SHA until a reviewed release tag exists.
 
+The generated gate uses `pull_request_target` only to load the validator workflow from the protected base branch. It checks out the candidate commit as inert data, runs no candidate scripts, disables persisted credentials, and executes validator code from the immutable Zaati revision. Candidate branches therefore cannot replace the workflow while preserving its check name.
+
+Add a ruleset or CODEOWNERS requirement for `.github/**` and `zaati.data.json` that requires a trusted human or GitHub team. The producing identity must not bypass that ruleset. Enable GitHub secret scanning and push protection where available.
+
 ## Bundle writes
 
-A daily producer creates one branch and pull request containing every current-date path. It must never publish a subset, write directly to the default branch, edit the validation workflow, or merge its own pull request. The independent gate compares the candidate with the authoritative expected source set and rechecks paths, ownership, schemas, privacy rules, and encryption mode.
+A daily producer creates one branch and pull request containing every current-date path. Candidate JSON exists in private Git history before pull-request validation runs, so minimize and scan it before the first push. The gate prevents invalid data from merging, not from entering a candidate branch. The producer must never publish a subset, write directly to the default branch, edit protected files, or merge its own pull request.
+
+Single-source and custom bundles use the same gate. Initialize the exact Prompt Studio selection with `--sources`:
 
-Single-source workers remain supported for independent cadences, but they use the same pull-request gate.
+```bash
+npm run data-repository:init -- --repository-root ../zaati-data --code-repository YOUR_USER/zaati-os --code-ref FULL_COMMIT_SHA --sources money:pulse
+```
 
 Same-day reruns replace the same file and preserve `snapshot_id`. Workers fetch the latest target branch before writing and never force-push.
 

docs/maintainer-setup.md

@@ -26,6 +26,8 @@ After the first successful runs, protect `main`:
 - block force pushes and branch deletion
 - apply the rules to administrators unless an emergency procedure says otherwise
 
+For every private data repository, add a second ruleset for `.github/**` and `zaati.data.json`. Require trusted-owner review and block the producer identity from bypassing it. The producer needs Contents and Pull requests write access only. It must have no Actions, Workflows, Administration, secrets, variables, environments, or repository-settings write access.
+
 Do not require the deployment workflow for code pull requests. It intentionally runs only for manual dispatch or configured main-branch deployment.
 
 ## Production environment

docs/onboarding.md

@@ -29,7 +29,7 @@ You need:
 - an LLM or automation environment that can use your approved sources and write to GitHub
 - a Cloudflare account and custom domain only when you are ready to deploy
 
-The contract is provider-neutral, but Zaati OS does not bundle source connectors. The maintained first real workflow is ChatGPT scheduled tasks. Other capable LLMs, local models, n8n, cron, and custom commands can use the same contract when they already have the required approved tools.
+The contract is provider-neutral, but Zaati OS does not bundle source connectors. ChatGPT scheduled tasks are the target first real workflow, with recorded release evidence still pending. Other capable LLMs, local models, n8n, cron, and custom commands can use the same contract when they already have the required approved tools.
 
 ## 1. Fork, clone, and personalize
 

docs/privacy.md

@@ -25,16 +25,18 @@ Users separately trust their selected source providers, LLM provider or local mo
 | Static bundle served publicly                   | `workers_dev` and preview URLs disabled, custom domain behind Access                         |
 | CI exposes data                                 | No private build artifacts, no snapshot logging, secrets only on protected deployment events |
 | A broad Access rule lets anyone in              | Deny by default, exact emails or constrained identity groups, unauthenticated preflight      |
-| Credential committed accidentally               | Common secret-shape scan, GitHub secret storage, scoped tokens                               |
+| Credential committed accidentally               | Common credential-shape scan, GitHub secret storage, scoped tokens, host push protection     |
 | Private snapshot repository is copied or leaked | Optional AES-256-GCM authenticated encryption with a separate deployment key                 |
 | Producer returns only part of a batch           | Authoritative expected-source comparison rejects missing, extra, or self-redefined bundles   |
-| Producer self-certifies unsafe output           | Independent private-repository pull-request validation before merge                          |
+| Producer self-certifies unsafe output           | Base-branch-controlled private-repository validation before merge                            |
 | Sensitive text hides inside a valid field       | Universal secret scanning plus source-specific content guards over every snapshot string     |
 
 ## Data minimization
 
 Keep a normalized action, measure, deadline, status, and evidence reference when they are enough. Avoid raw email bodies, full documents, attachments, statements, account identifiers, source code, customer data, authentication links, cookies, tokens, and unnecessary information about other people.
 
+Zaati detects common credential formats and source-specific risky shapes. No regular-expression list can identify every secret, medical fact, name, message excerpt, or unnecessary personal detail. Enable secret scanning and push protection on the private repository, minimize before the first branch push, and treat model and operator judgment as part of this boundary.
+
 ## Public fork rule
 
 A public fork may contain schemas, prompts, reusable source definitions, UI, and synthetic examples. It must not contain real snapshots, local instance configuration, a compiled private dashboard, screenshots of real data, or deployment secrets.