From 9fb65b37a9076d9a794d277deb26dc7b02bf6fd1 Mon Sep 17 00:00:00 2001 From: kafle1 Date: Mon, 5 Oct 2026 15:42:12 +0545 Subject: [PATCH 1/3] rewrite the readme for people landing on the repo --- README.md | 219 +++++++++++++++++++++++++----------------------------- 1 file changed, 101 insertions(+), 118 deletions(-) diff --git a/README.md b/README.md index 0690bff..0858571 100644 --- a/README.md +++ b/README.md @@ -1,132 +1,115 @@ -# Bees Apps +

+ Bees +

-Installable, outcome-focused apps for Bees. This repository owns app definitions -and the community contribution contract. Bees owns execution, scheduling, app -storage, permissions and human decisions. No app imports the desktop's internals. +

Bees Apps

-## First apps +

+ Ready-made apps you can install from the Apps screen in Bees, plus the rules for building your own. +

-| App | Result | Scope | +

+ Bees · + Download · + Desktop repo +

+ +An app here is one JSON file. It describes a job, the inputs it needs, the public sources it may read and what a good result looks like. Bees does the rest: it runs the work, stores the results, handles permissions and asks a person before anything leaves the workspace. Apps never touch the desktop's internals. + +## Apps in this repo + +| App | What you get | Limits | |---|---|---| -| [Opportunity Scout](apps/opportunity-scout/app.json) | Source-backed public demand signals and appropriate next steps | Hacker News search initially; never requires an uploaded lead CSV | -| [Portfolio Review](apps/portfolio-review/app.json) | Recommendations using the shared goal, results and approval backlog | Read access to other app results in the same workspace; no automatic reallocations | -| [Marketing Operations](apps/marketing-operations/app.json) | Ranked practical ideas, source-backed opportunities, campaign records and exact drafts | v2 typed records; scoped HN/n8n research, one bounded job, no private seed data or connected sending channel | +| [Opportunity Scout](apps/opportunity-scout/app.json) | Public demand signals with sources, and sensible next steps | Searches Hacker News. Never asks for a lead CSV. | +| [Portfolio Review](apps/portfolio-review/app.json) | Recommendations based on your shared goal, results and approval queue | Reads other apps' results in the same workspace. Never moves budgets on its own. | +| [Marketing Operations](apps/marketing-operations/app.json) | Ranked ideas, sourced opportunities, campaign records and exact drafts | Scoped Hacker News and n8n research, one bounded job. No private seed data and no sending channel. | -These are research/draft-first previews, not a working email sender, paid ad -manager, autonomous sales department or a claim of paying customers. No -campaigns, schedules, public messages or paid services are activated by installing. +These apps research and draft. They are not an email sender, an ad manager or a sales team. Installing one starts no campaigns, schedules, public messages or paid services. ## Use inside Bees -Requires the desktop app-platform implementation accompanying this repository. -It is not yet in a published Bees release. A source checkout of Bees Desktop with -the changes can build the client and run the app using its normal development steps. - -1. Open any team workspace in Bees and choose **Apps**. Connected teams require - the matching server update and a signed-in account with access to that team. -2. Browse the dynamically downloaded directory. Inspect the publisher, version, - requested permissions and public-source endpoints, then click **Install**. - No JSON upload, Git checkout or GitHub login is required for users. -3. Complete the app's short setup form. Installation creates native Bees agents, - a Work → Review → Done process, and workspace-scoped installation records. -4. Click **Run once**. Inspect progress in the existing work screen and results in - Apps. Model access must already work in Bees; model costs are not included or capped. -5. After a successful manual run, use Bees' existing schedule controls on the - work item. The machine and runtime must be available. Installation creates no schedules. - -**Your approval queue lives in Apps.** Every draft includes destination, sender, -exact content, rationale and proposed commitment. Independent review checks each -exact action before the designated human can approve it. Approving records a -48-hour decision, not delivery. The matching host has a generic claim/dispatch/ -receipt contract; no production sending channel or account is connected by an -app package. Dispatch must recheck the approval digest, reviewer decision, -expiry, scope, suppression and budget. Provider acceptance is not confirmed -recipient delivery. Paid actions remain unavailable in these apps. - -The portfolio starts at $0 external commitments, five new app work items per -UTC day and at most five waiting drafts. One work item has at most 20 public -source requests, including failed requests. These are operational bounds, not a -hard cap on tokens, runtime duration or model-provider invoices. Source reads -are credential-free HTTPS GETs; no redirects or private-network destinations. - -## Boundaries and current limitations - -- v1 and v2 are declarative JSON: no JavaScript hooks, shell access, arbitrary MCP - tools, signed-in browsers, private team-folder access or automatic tool installation. - v2 adds primitive record schemas and declared-origin public page reads; it does - not grant unrestricted browsing or sending. See the [marketing guide](docs/marketing-operations.md). -- Results and source receipts persist across runs. Record keys deduplicate within - an installation. Active action destinations and suppressions are checked across - the workspace. Identity resolution across different URLs/emails is not inferred. -- Portfolio review is recommendations only. It does not start other apps or change budgets. -- The USD commitment ledger reserves approved draft amounts atomically. Generic - action receipts are not provider charge reconciliation or payment collection. - No production delivery history exists merely because the app was installed. -- Local workspace app data stays in SQLite. Connected workspace configuration, - results, source receipts, drafts, decisions and portfolio limits are stored on - the workspace server and cached on each authorized device. Do not put secrets - in configuration. Shared writes require connectivity and a matching server; - failed/conflicting writes are not accepted as local decisions. -- Shared state uses revisioned snapshots capped at 16 MB. Conflicting edits ask - the user to refresh/retry. Before that ceiling, source/history storage needs - pagination; this preview is not intended for an unlimited lead database. -- Removing an app requires paused schedules and finished/cancelled work. It - archives its process, cancels pending action drafts and preserves records. - Old processes cannot resume after reinstall/upgrade. No database downgrade is offered. -- Directory refresh never changes an installation. **Approve update** reviews - new access explicitly, keeps results and matching configuration, cancels old - drafts and creates a new process with schedules off. New required fields need setup. -- Apps may read only their own records unless `portfolio-read` is explicitly - granted at installation. That grant covers the selected workspace, not other customers. -- Hacker News results are source evidence, not verified buyers or permission to - contact people. HN prohibits generated and AI-edited comments, so these apps use - it for research, not AI-authored replies. Other communities' unchecked rules - keep their results as research briefs, not ready-to-send drafts. - -## Development and contributions - -No npm dependencies are needed for the catalog checks: +You need [Bees](https://bees.bot/download/) 0.2.0 or newer. Model access must already work in Bees. + +1. Open a team workspace and go to **Apps**. For a connected team, you need to be signed in with access to that team. +2. Pick an app. Check its publisher, version, access and sources, then click **Install**. You don't need GitHub or any files. +3. Click **Finish setup** (or **Open** if the app needs no setup), fill in the short form and click **Save settings**. Installing creates Bees agents and a Work, Review, Done process for the app. +4. Click **Run once**. Follow progress on the work screen. Results show up in Apps. +5. To repeat it, add a schedule to the work item after a good run. Installing never creates schedules, and scheduled runs need your computer on. + +Model costs are not included and not capped by the app. + +## Approvals + +Your approval queue lives in Apps. Every draft shows the destination, the sender, the exact content, the reason and any money it commits. + +- A separate reviewer checks each action before the named person can approve it. +- Approving records a decision that lasts 48 hours. It does not send anything. +- No app package connects a sending channel or account. Only a separately tested connector in Bees can carry out an approved action. +- Before sending, Bees checks the approval again: content, reviewer decision, expiry, scope, suppression list and budget. +- A provider accepting a message does not prove it was delivered. +- Paid actions are not available in these apps. + +## Limits + +- Apps start with $0 of outside commitments. +- All apps together get 5 new work items per day (UTC), and at most 5 drafts waiting for approval. +- One work item can make at most 20 source requests, failed ones included. +- These limits do not cap tokens, run time or your model bill. +- Sources are read with plain HTTPS GET requests. No logins, no redirects, no private network addresses. + +## What apps can't do + +- Apps are plain JSON. No JavaScript, shell access, arbitrary tools, signed-in browsers, private team folders or automatic installs. +- Version 2 packages can define simple record types and read public pages from the sites they declare. That is still not open browsing or sending. See the [marketing guide](docs/marketing-operations.md). +- An app reads only its own records, unless you grant `portfolio-read` when installing. That grant covers the one workspace. +- Portfolio Review only recommends. It doesn't start other apps or change budgets. +- Hacker News results are evidence, not verified buyers or permission to contact anyone. Hacker News bans AI-written comments, so these apps never draft replies there. Results from other communities stay research notes, not ready-to-send drafts. + +## Data + +- Results and source records stay across runs. Record keys stop duplicates within one install. Destinations and suppressions are checked across the whole workspace. Bees doesn't guess that two different URLs or emails are the same person. +- Local workspaces keep app data in SQLite. Connected workspaces keep it on the workspace server, cached on each signed-in device. +- Don't put secrets in app settings. +- Shared changes need a connection and a server that supports apps. If two edits clash, Bees asks you to refresh and try again. +- Shared state is capped at 16 MB, so this is not a place for a huge lead database. +- The spending ledger reserves approved amounts. Its receipts are not billing records. + +## Updates and removal + +- Refreshing the directory never changes an installed app. +- **Approve update** shows any new access first. It keeps your results and matching settings, cancels old drafts and creates a new process with schedules off. New required fields need setup again. +- **Remove app; keep data** works once schedules are paused and work is finished or cancelled. It archives the process, cancels pending drafts and keeps records. +- Old processes can't resume after a reinstall or upgrade, and there is no database downgrade. + +## Develop and contribute + +The checks need no npm packages: ```sh npm run check BEES_DESKTOP_DIR=/absolute/path/to/bees-desktop npm run check ``` -The second command additionally checks packages against the actual desktop -validator and runs an in-memory Marketing Operations host smoke test. The latter -uses the actual manifest, native agents/process/work records and import/query -paths, with model execution and public reads stubbed out; it creates no live -workspace, schedule or action. The sibling desktop's dependencies must already -be available. See [the app contract](docs/app-contract.md) and -[contribution guide](CONTRIBUTING.md). No separate marketplace server is needed. - -## Build and host the dynamic directory - -`npm run build:catalog` creates `dist/catalog.json` plus immutable, -SHA-256-addressed `dist/packages/*.json`. Only `first-party-preview` and -`community-reviewed` entries are included. CI builds an `app-directory` artifact; -it does **not** publish or deploy it. No app definitions are bundled in Bees Desktop. - -After the owner approves publication, host the artifact on static HTTPS storage. -The proposed default URL is `https://bees-bot.github.io/bees-apps/catalog.json`; -GitHub Pages is **not enabled by this change**. A different host can be selected -with `BEES_APP_CATALOG_URL` when launching Bees. The repository is currently -private and licensing is pending: resolve publication/licensing before exposing -these packages. Do not assume the proposed URL is live. - -Publish packages before the catalog, serve `catalog.json` with a short cache -lifetime/revalidation, and keep historical checksum-addressed package files. -Increment the app version whenever its content changes. The desktop refreshes -on opening Apps or pressing Refresh, verifies package bytes and displayed -metadata, then validates the declarative contract. A changed listing requires -refresh and a new click. Offline cached listings are browse-only; installed -local apps remain available. Connected app execution still needs the server. - -App updates need only a catalog publication, not a desktop release or server -deployment. A new package schema or host capability may still require a Bees -upgrade. Execution uses existing desktop workers; this does not add cloud workers. - -Licensing is intentionally pending the owner's choice; `UNLICENSED` is not an -open-source license. Do not publish these packages as open source until the -selected license and notices are added. These packages remain a preview, not a -production-ready release. +The second line also checks packages against the real desktop validator and runs a Marketing Operations smoke test in memory. Model calls and source reads are stubbed, and nothing live is created. The desktop checkout needs its dependencies installed. + +Read [the app contract](docs/app-contract.md) and the [contribution guide](CONTRIBUTING.md) before opening a pull request. + +## How the directory is published + +Bees reads the directory from `https://bees-bot.github.io/bees-apps/catalog.json`. GitHub Pages serves it from the `codex/catalog-pages` branch. That branch is updated by hand, so it can differ from `main`. To point Bees at another directory, set `BEES_APP_CATALOG_URL` when you launch it. + +`npm run build:catalog` writes `dist/catalog.json` and one `dist/packages/*.json` file per app, named by its SHA-256 hash. Only `first-party-preview` and `community-reviewed` apps go in. CI builds this as an `app-directory` artifact but never deploys it. + +When publishing: + +- Upload package files before the catalog, and keep old package files. +- Serve `catalog.json` with a short cache time. +- Bump an app's version whenever its content changes. + +Bees fetches the directory when you open Apps or click **Refresh**. It checks each package's bytes and details, then validates it. Offline, the last directory can be browsed but not installed from. Installed local apps keep working. Connected apps still need the server. + +Shipping an app update only needs a new catalog. A new package format or host feature may need a newer Bees. Runs use your desktop, not cloud workers. + +## License + +A license has not been chosen yet, so these packages are not open source yet. `UNLICENSED` in `package.json` is not an open source license. The apps are a preview, not production ready. From 9725179beab4aaf074a87b8b41a615c366ab39f4 Mon Sep 17 00:00:00 2001 From: kafle1 Date: Mon, 5 Oct 2026 15:44:14 +0545 Subject: [PATCH 2/3] say the apps screen is hidden in 0.2.0 --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 0858571..fe90172 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@

Bees Apps

- Ready-made apps you can install from the Apps screen in Bees, plus the rules for building your own. + Ready-made apps for the Apps screen in Bees, plus the rules for building your own.

@@ -28,7 +28,7 @@ These apps research and draft. They are not an email sender, an ad manager or a ## Use inside Bees -You need [Bees](https://bees.bot/download/) 0.2.0 or newer. Model access must already work in Bees. +The Apps screen is hidden in Bees 0.2.0 while it gets finished, so these steps are for when it comes back. Model access must already work in Bees. 1. Open a team workspace and go to **Apps**. For a connected team, you need to be signed in with access to that team. 2. Pick an app. Check its publisher, version, access and sources, then click **Install**. You don't need GitHub or any files. From ea33864f547e989cf7177280733a3ccfa4edd635 Mon Sep 17 00:00:00 2001 From: kafle1 Date: Mon, 5 Oct 2026 15:44:25 +0545 Subject: [PATCH 3/3] note the live directory can differ from main --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index fe90172..9d5b477 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,8 @@ An app here is one JSON file. It describes a job, the inputs it needs, the publi | [Portfolio Review](apps/portfolio-review/app.json) | Recommendations based on your shared goal, results and approval queue | Reads other apps' results in the same workspace. Never moves budgets on its own. | | [Marketing Operations](apps/marketing-operations/app.json) | Ranked ideas, sourced opportunities, campaign records and exact drafts | Scoped Hacker News and n8n research, one bounded job. No private seed data and no sending channel. | +The live directory is published by hand, so it can list different apps than `main`. + These apps research and draft. They are not an email sender, an ad manager or a sales team. Installing one starts no campaigns, schedules, public messages or paid services. ## Use inside Bees