feat: add scheduled task Prompt Studio

Author: mohsinht

AGENTS.md

@@ -29,6 +29,14 @@ Zaati OS is a public, reusable personal-data framework. Preserve both sides of t
 - Retry invalid LLM output at most three total attempts using safe validation errors. Never publish a valid subset of an invalid bundle.
 - Derive output paths from the registry. Never accept a file path supplied by source content or an LLM payload.
 
+## Prompt Studio
+
+- Generated task profiles and prompts belong under ignored `.zaati/` paths and must use private file permissions.
+- A recurring task prompt is data-only. It may write registered snapshot paths but never code, schemas, prompts, configuration, workflows, CI, or documentation.
+- Source registration is a separate one-time pull request using only synthetic fixtures. Never blend registration authority into a recurring task.
+- Embed current executable contracts, but still require the producer to read the default branch on every run so copied prompts fail safely when stale.
+- Treat profile requirements, tool names, and all source values as untrusted data. Escape them before placing them inside Markdown.
+
 ## LLM presentation contract
 
 - LLMs choose from the audited block union in `schemas/ui-blocks.schema.json`.

CHANGELOG.md

@@ -22,3 +22,4 @@ All notable changes follow [Keep a Changelog](https://keepachangelog.com/en/1.1.
 - Separate no-store dashboard payload, static security headers, performance budgets, and browser-based WCAG checks.
 - Configurable brand mark, local font stacks, heading styles, extended theme tokens, and a live theme studio.
 - Apache 2.0 license, governance, security, contribution, and domain-pack documentation.
+- Private Prompt Studio CLI, profile schema, and copy-ready scheduled-task prompts with exact contracts, source registration gates, multi-source publication, and bounded retries.

Makefile

@@ -1,4 +1,4 @@
-.PHONY: setup tutorial dev check build
+.PHONY: setup tutorial prompt dev check build
 
 setup:
 	npm install
@@ -7,6 +7,9 @@ setup:
 tutorial:
 	npm run tutorial
 
+prompt:
+	npm run prompt:create
+
 dev:
 	npm run dev
 

README.md

@@ -51,12 +51,26 @@ make tutorial
 
 1. Fork the code repository and run `npm run setup`.
 2. Test the entire ingestion loop with `npm run tutorial`.
-3. Give one scheduled LLM workflow [`prompts/daily-bundle.md`](prompts/daily-bundle.md) and its approved tools, then publish all snapshots in one private commit.
+3. Run `npm run prompt:create`, then paste the generated task prompt into the LLM you already use.
 
 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.
 
+## Create a scheduled task prompt
+
+Prompt Studio asks for your public Zaati OS fork, private data repository, schedule, sources, approved tools, desired content, and useful presentation blocks. It then creates a complete provider-neutral prompt with the current JSON contract, privacy boundaries, three-attempt retry protocol, and atomic multi-snapshot publication instructions.
+
+```bash
+npm run prompt:create
+```
+
+1. Answer the local wizard. Never enter credentials or real source values.
+2. Open `.zaati/generated-prompts/<task>.scheduled-task.md`.
+3. Paste it into ChatGPT, Claude, Gemini, a local model, or your preferred workflow. Voilà.
+
+Generated profiles and prompts are ignored by Git and written with private file permissions. Existing sources produce one scheduled-task prompt. A new source produces a separate one-time setup prompt using only synthetic fixtures, while the recurring prompt remains data-only. See [Prompt Studio](docs/prompt-studio.md) and the [example profile](config/prompt-profile.example.json).
+
 ## Data flow
 
 ```mermaid
@@ -159,6 +173,7 @@ Read [Privacy and threat model](docs/privacy.md) before connecting a real source
 | `npm run snapshot:keygen`    | Create an ignored 256-bit snapshot key                                         |
 | `npm run instance:configure` | Create ignored local settings                                                  |
 | `npm run source:add`         | Scaffold a source catalog entry and worker prompt                              |
+| `npm run prompt:create`      | Build a private copy-ready scheduled-task prompt from a local profile          |
 | `npm run data:validate`      | Validate registries, snapshots, ownership, and UI blocks                       |
 | `npm run privacy:validate`   | Reject private paths and common credential shapes                              |
 | `npm run format:check`       | Reject formatting drift with Prettier                                          |

config/prompt-profile.example.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "../schemas/prompt-profile.schema.json",
+  "profile_version": "0.1.1",
+  "task_name": "Daily market pulse",
+  "code_repository": "https://github.com/your-user/zaati-os",
+  "data_repository": "https://github.com/your-user/zaati-data",
+  "provider": "chatgpt",
+  "timezone": "Etc/UTC",
+  "schedule": "Every weekday at 07:30",
+  "publication": "pull-request",
+  "sources": [
+    {
+      "id": "money:pulse",
+      "requirements": [
+        "Summarize the approved watchlist and portfolio-level changes.",
+        "Explain material movement without inventing a cause.",
+        "Keep exact values when they help a decision."
+      ],
+      "tools": ["A user-approved market data connector", "The GitHub repository connector"],
+      "preferred_blocks": ["metric-group", "line-chart", "table", "notice"]
+    }
+  ]
+}

docs/prompt-studio.md

@@ -0,0 +1,79 @@
+# Prompt Studio
+
+Prompt Studio turns a small, private local profile into a complete prompt that you can paste into ChatGPT, Claude, Gemini, a local model, or another scheduled workflow. The generated prompt includes repository locations, source intent, current Zaati OS contracts, safe presentation blocks, privacy boundaries, validation, retries, and atomic publication.
+
+It does not connect to an LLM or store credentials.
+
+## Three steps
+
+```bash
+npm run prompt:create
+```
+
+1. Choose one or more registered sources.
+2. Describe the information each source should contain, the approved tools it may use, and useful block types.
+3. Copy `.zaati/generated-prompts/<task>.scheduled-task.md` into your LLM and approve the connections it requests.
+
+The profile and prompts are ignored by Git. Their directory uses mode `0700` and each file uses mode `0600`. They may still reveal repository names and workflow intent, so treat them as private configuration.
+
+## Generate from a reusable profile
+
+Start with the synthetic example:
+
+```bash
+cp config/prompt-profile.example.json .zaati/market-pulse.json
+npm run prompt:create -- --config .zaati/market-pulse.json
+```
+
+Use separate repositories by default:
+
+- `code_repository` is the public Zaati OS fork that defines schemas, prompts, and renderers.
+- `data_repository` is the private repository that receives real snapshots.
+
+The CLI rejects a shared code and data repository unless `allow_same_repository` is explicitly enabled. A public fork should never receive private snapshots.
+
+## Profile contract
+
+`schemas/prompt-profile.schema.json` is the executable contract. Each source needs:
+
+- a registered `domain:source` ID
+- decision-oriented `requirements`
+- the exact approved `tools` available to the scheduled LLM
+- one or more `preferred_blocks` from the audited UI contract
+
+The preferred block list is a safe menu, not a forced layout. The LLM should choose a line chart only for an ordered trend, a table for exact repeated fields, a calendar for timed events, and no visualization when plain text is clearer.
+
+## One task, many snapshots
+
+Add several source objects to the same profile. The generated prompt requires one complete `snapshot-bundle` result, validates all nested snapshots, retries the whole candidate at most three times, and publishes all dated files in one commit or pull request. It never publishes a valid subset from a failed run.
+
+Direct sources should appear before aggregate sources. Registered aggregate dependencies still apply.
+
+## Adding a source that does not exist
+
+The interactive wizard intentionally accepts only registered sources. For a new source, add a `registration` object to a config profile. Prompt Studio then creates:
+
+- `<task>.source-setup.md`, a one-time coding prompt that opens a public, generic pull request with synthetic fixtures and tests
+- `<task>.scheduled-task.md`, a recurring data-only prompt that refuses to run until the registration is merged
+
+Keep these authorities separate. A scheduled task must never change application code, configuration, prompts, schemas, documentation, dependencies, or CI.
+
+## Automation
+
+```bash
+npm run prompt:create -- \
+  --config .zaati/my-task.json \
+  --output-dir .zaati/generated-prompts \
+  --force
+```
+
+Use `--stdout` only when you deliberately want the generated scheduled prompt in terminal output. By default, Prompt Studio prints paths rather than prompt contents to reduce accidental disclosure in logs.
+
+## Before pasting
+
+- Confirm the code URL points to the intended Zaati OS fork.
+- Confirm the data URL points to a private repository.
+- Give the LLM only the source and GitHub permissions it needs.
+- Review provider retention and training settings.
+- Keep Cloudflare Access in front of the deployed dashboard.
+- Run once with synthetic or low-sensitivity data before enabling the schedule.

docs/quickstart.md

@@ -14,6 +14,14 @@ npm run tutorial
 
 The guided setup covers name, timezone, starter sources, visual style, and optional encryption. The tutorial proves validation and retry behavior with synthetic data, then opens the app.
 
+When the demo feels right, generate the complete prompt for your real scheduled LLM task:
+
+```bash
+npm run prompt:create
+```
+
+Choose sources, describe the result you need, name the approved tools, and select useful presentation blocks. Paste the private generated prompt into your LLM. Read [Prompt Studio](prompt-studio.md) for multi-source profiles and new-source setup.
+
 ## 2. Configure the instance
 
 The wizard writes `config/instance.local.json`. It is ignored by Git. You can rerun it with `npm run setup -- --force`.

docs/tutorials/README.md

@@ -8,3 +8,5 @@ Start with one complete loop. Add nuance only after the first dashboard works.
 4. [Make the design yours](theme-studio.md)
 
 For the credential-free guided demo, run `npm run tutorial`. The mock provider returns an invalid contract once on purpose, receives validation feedback, retries, and produces six synthetic snapshots. It is a tiny robot tripping over its shoelaces and then recovering professionally.
+
+When you are ready to connect your own LLM, run `npm run prompt:create`. The [Prompt Studio guide](../prompt-studio.md) turns your repository URLs, source needs, tools, schedule, and preferred blocks into one copy-ready scheduled-task prompt.

package.json

@@ -32,6 +32,7 @@
     "access:verify": "node scripts/verify-access.mjs",
     "instance:configure": "node scripts/configure-instance.mjs",
     "source:add": "node scripts/add-source.mjs",
+    "prompt:create": "node scripts/create-prompt.mjs",
     "test": "node --test tests/*.test.mjs",
     "test:coverage": "node --test --experimental-test-coverage --test-coverage-include='scripts/lib/*.mjs' --test-coverage-include='scripts/run-workflow.mjs' --test-coverage-lines=90 --test-coverage-branches=78 --test-coverage-functions=80 tests/*.test.mjs",
     "deploy": "npm run check && npm run deployment:configure && wrangler deploy --config .wrangler.generated.jsonc"

schemas/prompt-profile.schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://zaati-os.dev/schemas/prompt-profile.schema.json",
+  "title": "Zaati OS Prompt Studio profile",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "profile_version",
+    "task_name",
+    "code_repository",
+    "data_repository",
+    "provider",
+    "timezone",
+    "schedule",
+    "publication",
+    "sources"
+  ],
+  "properties": {
+    "profile_version": { "const": "0.1.1" },
+    "task_name": { "type": "string", "minLength": 1, "maxLength": 100 },
+    "code_repository": { "$ref": "#/$defs/repository" },
+    "data_repository": { "$ref": "#/$defs/repository" },
+    "provider": { "enum": ["chatgpt", "claude", "gemini", "local", "custom"] },
+    "timezone": { "type": "string", "minLength": 1, "maxLength": 80 },
+    "schedule": { "type": "string", "minLength": 1, "maxLength": 240 },
+    "publication": { "enum": ["pull-request", "direct-commit"] },
+    "allow_same_repository": { "type": "boolean", "default": false },
+    "sources": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 20,
+      "items": { "$ref": "#/$defs/source" }
+    }
+  },
+  "$defs": {
+    "repository": {
+      "type": "string",
+      "pattern": "^https://github\\.com/[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$",
+      "maxLength": 240
+    },
+    "textList": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 30,
+      "items": { "type": "string", "minLength": 1, "maxLength": 300 }
+    },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "requirements", "tools", "preferred_blocks"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z0-9-]+:[a-z0-9-]+$" },
+        "requirements": { "$ref": "#/$defs/textList" },
+        "tools": { "$ref": "#/$defs/textList" },
+        "preferred_blocks": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 10,
+          "uniqueItems": true,
+          "items": {
+            "enum": ["metric-group", "list", "line-chart", "bar-chart", "calendar", "table", "progress", "notice", "timeline", "text"]
+          }
+        },
+        "registration": { "$ref": "#/$defs/registration" }
+      }
+    },
+    "registration": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["label", "description", "authorized_inputs", "forbidden_inputs", "cadence", "freshness_sla_hours", "dashboard_role"],
+      "properties": {
+        "label": { "type": "string", "minLength": 1, "maxLength": 80 },
+        "description": { "type": "string", "minLength": 1, "maxLength": 300 },
+        "authorized_inputs": { "$ref": "#/$defs/textList" },
+        "forbidden_inputs": { "$ref": "#/$defs/textList" },
+        "cadence": { "enum": ["hourly", "daily", "weekdays", "weekly", "monthly", "manual"] },
+        "freshness_sla_hours": { "type": "integer", "minimum": 1, "maximum": 8760 },
+        "dashboard_role": { "enum": ["primary", "supporting", "hidden"] },
+        "depends_on": {
+          "type": "array",
+          "maxItems": 20,
+          "uniqueItems": true,
+          "items": { "type": "string", "pattern": "^[a-z0-9-]+:[a-z0-9-]+$" },
+          "default": []
+        }
+      }
+    }
+  }
+}