Skip to content

quickstart.md

Latest commit

 

History

History
73 lines (46 loc) · 3.44 KB

quickstart.md

File metadata and controls

73 lines (46 loc) · 3.44 KB
Raw

Quickstart

This guide takes a new user from fork to a working synthetic dashboard, then to one real multi-source workflow without placing personal data in the public fork.

1. Fork and explore the demo

git clone https://github.com/YOUR_GITHUB_USERNAME/zaati-os.git
cd zaati-os
npm install
npm run dev

The first visit offers an optional guided tour of sources, component contracts, rendered results, example task prompts, and the private setup path.

The Synthetic demo workflow always builds and checks public fixtures on pushes to main. Deployment is opt-in so a fresh fork stays green before GitHub Pages exists. To publish it, enable Settings > Pages > GitHub Actions, add the repository variable ZAATI_ENABLE_DEMO_PAGES=true, then run the workflow or push to main.

When the demo feels right, create an ignored private workspace and verify the ingestion loop:

npm run setup
npm run tutorial
npm run prompt:create

Setup disables synthetic example fallback, Component Lab, copy-prompt guides, and the automatic demo tour. The tutorial remains available as clearly labeled synthetic test data inside the private shell.

Choose a provider and starter dashboard, then enter your public code fork and private data repository. Review the generated permission receipt before pasting the prompt into your LLM. Read Prompt Studio for advanced 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.

3. Choose a data boundary

For experimentation, write snapshots under ignored data/snapshots/.

For production, keep the public code fork clean and create a separate private data repository. Install its independent validator before connecting an LLM:

npm run data-repository:init -- --repository-root ../zaati-data --code-repository YOUR_USER/zaati-os --code-ref FULL_COMMIT_SHA

Require the Validate Zaati snapshots check on the private repository's default branch. Follow Private data repository.

4. Connect one multi-source workflow

A complete daily overview set is:

  • agenda:primary
  • inbox:attention
  • work:focus
  • money:pulse
  • news:briefing
  • overview:daily

Open prompts/daily-bundle.md and prompts/scheduled-github-bundle.md. Replace their repository, source, and timezone placeholders. Give them to the LLM workflow that already has approved access.

Run the complete prompt manually before scheduling it. One run should open one pull request containing all selected dated files. The LLM must never merge or bypass the independent check. For a trusted command adapter, pipe exact JSON into the local transaction:

your-llm-command | npm run snapshot:ingest -- --output-dir data/snapshots

5. Build aggregates last

Build all five non-aggregate snapshots first in memory. The overview can then use those validated candidates in the same run and commit. For a smaller independent bundle, omit the overview rather than silently omitting its dependencies.

6. Deploy privately

First deploy synthetic data to a custom Cloudflare hostname. Configure an exact Access Allow policy, verify the unauthenticated challenge, then connect the private data repository and enable production deployment.

Do not use public Pages, workers.dev, preview URLs, or obscurity for real snapshots. Follow Cloudflare deployment.