@omega.js/extension 0.1.0

package/docs/publishing.md

@@ -0,0 +1,182 @@
+# Publishing
+
+`OMEGA_IS_PUBLISH=true npm run build` packages AND uploads to extension stores in one step.
+
+## Supported stores
+
+- **Chrome Web Store** (Chrome / Edge / Brave / Opera users)
+- **Firefox Add-ons** (AMO)
+- **Microsoft Edge Add-ons** (separate from Chrome Web Store — Edge Insiders + corporate environments)
+
+Only stores with configured credentials get published to. Unconfigured stores are silently skipped.
+
+## Setup — `.env`
+
+Add store credentials to your project's `.env` (gitignored):
+
+```bash
+# Chrome Web Store
+CHROME_EXTENSION_ID="..."
+CHROME_CLIENT_ID="..."
+CHROME_CLIENT_SECRET="..."
+CHROME_REFRESH_TOKEN="..."
+
+# Firefox Add-ons
+FIREFOX_EXTENSION_ID="..."
+FIREFOX_API_KEY="..."
+FIREFOX_API_SECRET="..."
+
+# Microsoft Edge Add-ons
+EDGE_PRODUCT_ID="..."
+EDGE_CLIENT_ID="..."
+EDGE_API_KEY="..."
+```
+
+## Getting credentials
+
+### Chrome Web Store
+
+1. Create an OAuth client via [Google Cloud Console](https://console.cloud.google.com/) (Web application type)
+2. Enable the [Chrome Web Store API](https://developer.chrome.com/docs/webstore/using_webstore_api/)
+3. Generate a refresh token via the OAuth flow (one-time)
+4. `CHROME_EXTENSION_ID` is in your Chrome Web Store Developer Dashboard URL: `chrome.google.com/webstore/devconsole/<id>`
+
+### Firefox Add-ons
+
+1. Sign in to [Add-on Developer Hub](https://addons.mozilla.org/developers/)
+2. Generate JWT credentials at "Manage API Keys"
+3. `FIREFOX_EXTENSION_ID` matches the `id` field in your manifest's `browser_specific_settings.gecko.id`
+
+> **Declare `browser_specific_settings.gecko.id` before your FIRST publish.** Packaging no longer waits for it: with none declared, the firefox pass DERIVES `extension@<brand.url host>` (or `extension@<brand.id>.extension` when the brand has no url) and builds, failing only when there are no brand facts at all to derive from — so a fresh scaffold produces an artifact out of the box. Declare your own anyway before you submit: the id must stay stable across every release, an id assigned at submission time can never be changed from a self-hosted build, and `brand.url` can change under a derived one ([#574](https://github.com/Omega-JS-Stack/omega/issues/574)). The same pass translates the chrome-only panel keys (`side_panel` → `sidebar_action`, `sidePanel` permission dropped), so the firefox artifact is a real firefox artifact ([#264](https://github.com/Omega-JS-Stack/omega/issues/264)).
+
+### Microsoft Edge Add-ons
+
+1. Sign up for the [Microsoft Edge Add-ons Partner Center](https://partner.microsoft.com/dashboard/microsoftedge)
+2. Generate API credentials in the "API publishing" section
+3. `EDGE_PRODUCT_ID` is the GUID assigned to your extension by Microsoft
+
+## Publish flow
+
+```bash
+OMEGA_IS_PUBLISH=true npm run build
+```
+
+What happens:
+
+1. `npm run build` runs the full gulp pipeline (build → package → packaged/<browser>/raw + zip)
+2. `gulp/tasks/package.js` detects `OMEGA_IS_PUBLISH=true`
+3. For each browser, reads the store credentials from `.env`
+4. If credentials are present, uploads the `.zip` via the store's API
+5. Logs success / failure per store; exits non-zero if any upload fails
+
+## Manual upload
+
+Run `npm run build` without `OMEGA_IS_PUBLISH=true` — you get unsigned `.zip` files per browser under `packaged/`:
+
+```
+packaged/
+├── chromium/<ExtensionName>.zip
+├── firefox/<ExtensionName>.zip
+└── opera/<ExtensionName>.zip
+```
+
+Upload these manually via each store's web dashboard.
+
+## CI / GitHub Actions
+
+For automated releases, store credentials as encrypted GitHub Actions secrets. A typical workflow:
+
+```yaml
+- name: Build + publish
+  env:
+    OMEGA_IS_PUBLISH:        true
+    CHROME_EXTENSION_ID:   ${{ secrets.CHROME_EXTENSION_ID }}
+    CHROME_CLIENT_ID:      ${{ secrets.CHROME_CLIENT_ID }}
+    CHROME_CLIENT_SECRET:  ${{ secrets.CHROME_CLIENT_SECRET }}
+    CHROME_REFRESH_TOKEN:  ${{ secrets.CHROME_REFRESH_TOKEN }}
+    # ...same for FIREFOX_*, EDGE_*
+    GOOGLE_ANALYTICS_SECRET: ${{ secrets.GOOGLE_ANALYTICS_SECRET }}
+  run: npm run build
+```
+
+**The store credentials are not the only secret CI needs.** A dispatched run has no `.env`, so `GOOGLE_ANALYTICS_SECRET` — the Measurement Protocol secret the build BAKES into `OMEGA_BUILD_JSON` — only reaches the build through the workflow env. Without it, a CI-published extension shipped an empty secret and sent no analytics events, silently ([#582](https://github.com/Omega-JS-Stack/omega/issues/582)). The scaffolded `publish.yml` injects it, and a build-mode build of a brand that HAS `analytics.providers.google.id` fails loudly when the secret is empty rather than publishing a dead sender.
+
+Same pattern EM uses for its desktop apps. Each store does its own review afterward (Chrome / Firefox: hours to a few days; Edge: typically same day).
+
+## What about Safari?
+
+Safari (Apple) uses a different extension model and requires Xcode-based packaging via `safari-web-extension-converter`. Not currently in scope for @omega.js/extension's auto-publish. Manual conversion + App Store Connect upload is the route.
+
+## Store listing description (`config/description.md`)
+
+`config/description.md` is the Chrome Web Store listing description. When writing or rewriting it, first read `config/omega.json5` (brand), `config/messages.json` (extension name + short description), `src/manifest.json` (permissions/features), and the component JS under `src/assets/js/components/` to understand what the extension actually does — be specific about real features, not generic copy.
+
+The package task renders `{{ brand.* }}` tokens against `config/omega.json5` before writing `packaged/assets/description/<lang>.md` — the English source and every translated variant — so the store listing carries the resolved brand, never a literal token.
+
+**Format:**
+
+```
+[emoji] [Key Feature Headline 1]
+[emoji] [Key Feature Headline 2]
+[emoji] [Key Feature Headline 3]
+[emoji] [Key Feature Headline 4]
+[emoji] [Key Feature Headline 5]
+
+[Extension Name] is [compelling one-sentence pitch]. [Pain point 1]. [Pain point 2]. [Pain point 3].
+If you [target audience description] — [Extension Name] was made for you.
+
+[emoji] How it works
+[Extension Name] [brief mechanism description].
+
+[emoji] [Feature 1]: [One-line description]
+[emoji] [Feature 2]: [One-line description]
+[emoji] [Feature 3]: [One-line description]
+[emoji] [Feature 4]: [One-line description]
+
+[Brief usage instructions — 2-3 sentences].
+No complicated setup. No learning curve. Just [core value proposition].
+
+[emoji] Why [Extension Name] is a game changer
+
+[Benefit 1 title]: [Description].
+[Benefit 2 title]: [Description].
+[Benefit 3 title]: [Description].
+[Benefit 4 title]: [Description].
+[Benefit 5 title]: [Description].
+
+[emoji] The [Extension Name] Difference
+Most people either:
+
+[Alternative 1 that's worse]
+[Alternative 2 that's worse]
+
+[Extension Name] gives you a [better option description].
+[Catchy metaphor with emoji]
+[Closing sentence about who benefits].
+
+[emoji] Install [Extension Name] now and [call to action].
+[Short imperative sentence].
+
+:money_with_wings: Bonus:
+While you're browsing, the extension also finds and applies shopping deals from top partners like Amazon, Capital One, and NordVPN. Get discounts and bonuses without lifting a finger. When you buy through links on our extension, we may earn an affiliate commission.
+
+:locked_with_key: Your privacy is respected — we do not sell or misuse your data. By using our extension, you agree to our terms of service and privacy policy.
+When you buy through links on our extension, we may earn an affiliate commission.
+```
+
+**Rules:**
+
+- **Keep the Bonus section and Privacy section EXACTLY as shown** — do not modify these
+- Name the extension with `{{ brand.name }}` (or its literal name from `config/messages.json`) — the token resolves at package time
+- Be specific about features — reference what the code actually does
+- Tone: enthusiastic, conversational, persuasive; emojis for section headers and feature bullets
+- Feature headlines short and punchy (under 50 characters)
+- 300-500 words (excluding the Bonus and Privacy sections)
+
+**After rewriting**, clear stale cached translations — delete `.cache/translations/description/` and the `description` key from `.cache/translate.json` — then have the user run `npm run build` to regenerate translations (see [translations.md](translations.md)).
+
+## See also
+
+- [build-system.md](build-system.md) — packaging pipeline that produces the per-browser zips
+- [hooks.md](hooks.md) — `build:pre` and `build:post` hooks run before/after publish
+- [cli.md](cli.md) — env var conventions

package/docs/shared/agent-docs.md

@@ -0,0 +1,89 @@
+# Brand agent-docs chain (AGENTS.md / CLAUDE.md)
+
+**The problem**: every brand needs current framework guidance for AI agents, but copying it into each brand drifts. **The design (Ian 2026-07-20, amended 2026-07-27)**: every brand reads the SAME entry the monorepo uses — the top-level omega `AGENTS.md`, the map — and the map's pointers (plus the omega plugin's hooks) orchestrate which docs load. The brand-root knowledge itself lives in `docs/manager/brand.md`; no AGENTS.md anywhere carries content.
+
+## The chain
+
+```
+brand/CLAUDE.md            @AGENTS.md                          (one line, Claude Code's entry)
+brand/AGENTS.md   line 1:  @node_modules/@omega.js/AGENTS.md  (the top-level omega map — see below)
+                  below:   `# <brand> — brand notes` + the brand's own notes — NEVER touched by the framework
+```
+
+`node_modules/@omega.js/AGENTS.md` is a SYMLINK the workspace service maintains: it resolves the framework monorepo through the installed manager package's real path and links straight at the live top-level map. It sits in the scope directory — no package in the path — because the map belongs to the ecosystem, not to any one package. A published install has no monorepo above the package, so the link lands on the map prepare vendored INTO it (`@omega.js/manager/docs/AGENTS.md`, below). The two candidates are tried in that order, live map first, so a locally linked brand never lands on the generated copy sitting in that same monorepo's `packages/manager` ([#144](https://github.com/Omega-JS-Stack/omega/issues/144)).
+
+(The cp244 marker comment under the import was culled — Ian 2026-07-20: keep it short. Heals no longer scrub legacy copies (#148): a leftover marker or retired import line is consumer content, removed by hand per [breaking-changes.md](breaking-changes.md).)
+
+- The import path is **relative** (portable to any machine). For hoisted installs (the in-repo test brands are npm workspaces of this monorepo) the ensure step walks up and writes the correct depth, e.g. `@../../node_modules/@omega.js/AGENTS.md`.
+- The service resolves the monorepo through the installed manager package's real path (the local-era `file:` symlink), so the link always lands on the LIVE top-level map — framework edits are instantly visible to every brand session.
+- Non-Claude agents read `AGENTS.md` but don't follow `@` imports — the import line itself names the target path for them.
+
+## Maintenance
+
+`npm run manage` (the manage cycle's `workspace` service, `agents` op — `packages/manager/src/services/workspace/ensure/agents.js`, logic in `src/lib/agents-md.js`):
+
+| State found | Action |
+|---|---|
+| No `AGENTS.md` | Created: import + brand-notes skeleton |
+| Import present at line 1 (right depth) | No-op |
+| Import missing / not first / stale depth | Healed: resolved import moved to line 1, duplicates removed, consumer content preserved verbatim |
+| No `CLAUDE.md` | Created as the one-line `@AGENTS.md` pointer |
+| `CLAUDE.md` carries content | WARNED (never clobbered) with the move-it-to-AGENTS.md message |
+
+Pinned by `packages/manager/test/agents-md.test.js` (no package agent docs + files whitelist, guide-link create/heal/skip against both the local-era and published-install shapes, path resolution, create/heal/idempotence, content preservation).
+
+## Published packages carry their own docs ([#64](https://github.com/Omega-JS-Stack/omega/issues/64))
+
+A consumer install has no monorepo to point at, so the prepare lane ships the knowledge INSIDE each publishable. The devkit vendor hook every framework already runs (`packages/devkit/tools/vendor-docs.js`, called from `tools/vendor.js`) copies, for `@omega.js/{backend,client,desktop,extension,manager,web}`:
+
+| Monorepo source | Shipped as | Notes |
+|---|---|---|
+| `docs/<package>/` | `<package>/docs/` (flat) | The guide lands at `docs/index.md`, beside the package's committed deep docs; nested dirs (`classy-v2/`) survive |
+| `docs/shared/` | `<package>/docs/shared/` | The cross-framework contracts, verbatim |
+| `AGENTS.md` (the repo-root map) | `manager/docs/AGENTS.md` | Manager ONLY — the target the brand chain's scope symlink lands on when there is no monorepo. Links retargeted (see below) |
+| `agent-plugins/claude/` | `manager/claude-plugin/` + `manager/.claude-plugin/marketplace.json` | Manager ONLY — the plugin every brand enables (see below). `.mcp.json` ships WITH it: since [#144](https://github.com/Omega-JS-Stack/omega/issues/144) it launches `mcp-router-launch.js` inside the plugin, which node-resolves `@omega.js/mcp-router` from the install around it (a real dependency of the manager) instead of addressing the monorepo tree |
+
+The guide's monorepo-relative links are rewritten to the shipped layout on the way in (`../../packages/<self>/` → `../`, `../shared/` → `shared/`), so `docs/index.md` still reaches the package's deep docs, its README, and the shared contracts. Cross-framework links (`../backend/index.md`) are left verbatim — another framework's guide isn't in this tarball.
+
+The map's links are repo-root-relative, so it gets its own pass (`rewriteMapLinks`): `docs/shared/<x>.md` → `shared/<x>.md`, `docs/manager/<x>.md` → `<x>.md` (the manager's guide tree lands flat in the same dir), `docs/<other>/<x>.md` → `../../<other>/docs/<x>.md` (a sibling package under the same `@omega.js` scope), and a `packages/…` or `brands/…` link keeps its words while losing the link — no published target exists. A sibling that never publishes (`devkit`) or isn't installed leaves a dead relative link, the same trade the guide trees already make.
+
+Everything written is GENERATED: gitignored per package, cleared before each rewrite, and pinned by `packages/devkit/test/vendor-docs.test.js` (fixture monorepo) plus `scripts/vendor-docs.test.js`, which packs all six documented packages for real and reads the tarball listings.
+
+Version-matched by construction: the docs in `node_modules/@omega.js/web/docs/` are the docs of the version installed there.
+
+## Brands enable the plugin from their installed manager ([#62](https://github.com/Omega-JS-Stack/omega/issues/62))
+
+The plugin rides in `@omega.js/manager` because that is the package every brand installs. The workspace service's `claude-settings` op writes/heals the brand's committed `.claude/settings.json`:
+
+```json
+{
+  "extraKnownMarketplaces": { "omega": { "source": { "source": "directory", "path": "./node_modules/@omega.js/manager" } } },
+  "enabledPlugins": { "omega@omega": true }
+}
+```
+
+Committed, so every collaborator's session in that brand loads the omega skills and hooks — a directory marketplace is read LIVE from that path, so `npm update` moves the plugin with the package. The op only fires on a PUBLISHED install: `node_modules/@omega.js/manager` must carry the vendored `.claude-plugin/marketplace.json` **and** be a real directory. A locally linked brand's manager is a SYMLINK into the monorepo — whose `packages/manager` grows that same generated marketplace on every prepare — so the link itself is the local-era signal and the step skips; the developer's own user-scope install covers those sessions. The brand file NEVER points at a monorepo path — it would be machine-specific.
+
+Once loaded, the plugin's hooks make the chain BINDING in that brand: the inject hook discovers every target the brand declares and asks for each one's skill plus this map as required reading, and the gate hook refuses a write under `targets/<t>/` or to `config/omega.json5` until the skill owning that surface has been invoked. Mechanics and the surface table: [the plugin README](../../agent-plugins/claude/README.md).
+
+The gate reads the same way for a human's chat and for an agent that has no Skill tool, through two lanes and no others ([#760](https://github.com/Omega-JS-Stack/omega/issues/760)). In the main chat, invoking the skill IS the record. A subagent that writes its files through Bash reads the guide its brief names and then runs the one sanctioned command, `agent-plugins/claude/hooks/gate/mark.sh <skill>` here (in a brand: `node_modules/@omega.js/manager/claude-plugin/hooks/gate/mark.sh`), which writes the marker the hook would have written. A hand-written marker is a process breach, not a shortcut. Both lanes, and the flags: [the plugin README](../../agent-plugins/claude/README.md).
+
+Reading the chain is one half; acting on it is the other. The guard hook holds the other half in the same brand: a `Write|Edit` to a framework-owned file is refused with the upstream-first message ([#452](https://github.com/Omega-JS-Stack/omega/issues/452)). Generated and vendored files — `node_modules/`, any `dist/`, a generated header, the OMEGA-managed `database.rules.json` — are hard-refused and name the real source to edit; a SHADOW COPY, a brand file whose path mirrors a file the installed framework ships through its override layer (read from `node_modules/@omega.js/<framework>/`, never a hardcoded list), is refused with the two exits: file the framework issue, or declare the override with `omega:consumer-override: <reason>` in the file's first five lines (`omega customize` writes that marker itself, so a materialized file passes as it lands). Only the override MECHANISM is guarded: a brand's pages are content and its documented entry files are its own, so neither is ever refused. The monorepo is exempt and everything unrecognized fails open. The lookup-root table and the class rules: [the plugin README](../../agent-plugins/claude/README.md).
+
+## Packages carry no agent docs (Ian 2026-07-27)
+
+No `packages/<pkg>/` has an `AGENTS.md` or `CLAUDE.md` — deleted outright, no exceptions. Monorepo sessions get the map from the parent walk; consumer brands get it through the maintained scope symlink; a standalone package install has no resolvable chain anyway; the publish era generates whatever a shipped package needs ([#64](https://github.com/Omega-JS-Stack/omega/issues/64)).
+
+## The one deliberate gap
+
+- **`brands/sandbox-brand` carries NO agent-docs chain.** It is a synthetic fixture the automated corpus/e2e runs mangle and reset — nothing durable lives there, so nothing agent-facing is written there.
+
+## Editing the guide
+
+The brand-root guide is [docs/manager/brand.md](../manager/brand.md) — framework-owned, brand-agnostic (structure, verbs, per-target required-reading pointers, hard rules). Brand-specific knowledge belongs below the import in that brand's own `AGENTS.md`.
+
+## Per-target docs — RETIRED in brand context (cp246)
+
+Per-target `AGENTS.md`/`CLAUDE.md`/`CHANGELOG.md`/`docs/` scaffolds predate the brand-monorepo era; Claude Code walks parent directories, so the brand-root chain covers target-dir sessions. The shared defaults engine now has a `retire` fileMap rule (devkit `defaults-engine.js`), wired mirrored in all four frameworks' brand branches (detection = the existing `@omega.js/config` brand-root resolution): in a brand target those files NEVER scaffold; an existing framework-owned-only copy (Custom section empty/whitespace or byte-equal to the shipped boilerplate; marker-less files must equal the rendered template) is deleted once, loudly; a copy carrying real consumer content is preserved with a move-it-to-the-brand-root warning. Standalone projects keep full per-project doc scaffolding, and it follows the same shape as a brand root (#63): the framework template is an `AGENTS.md` (marker-merged, so consumer notes below the Custom marker survive every setup) beside a one-line `@AGENTS.md` `CLAUDE.md` pointer. Test-pinned both ways.
+
+**Prior-generation files ([#101](https://github.com/Omega-JS-Stack/omega/issues/101)).** A destination carrying the OMEGA section markers when the current template no longer does is a file an EARLIER generation of the same framework generated — the pre-#63/#91 content-bearing `CLAUDE.md` against today's one-line pointer. Its markers are the framework's own signature, so the engine treats it as framework-owned on both paths: the brand branch retires it (instead of keeping it behind a false "carries consumer content" warning), and on the standalone upgrade path `overwrite: false` still heals it to the current template (instead of leaving a stale doc beside the new `AGENTS.md`). A file with no markers is judged as before — consumer-authored unless it equals the rendered template.