Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -13,11 +13,11 @@ An admin-managed feature is configured by admin/platform operators and consumed
- Tenant feature enabled only for selected plans or accounts.
- Browser automation where admin controls allowed domains and runtime policy.
## Required Manifest Entries
## Required ticket contract
The feature manifest must declare:
The owning ticket doc must declare:
- `integration.ownership = "admin-managed"` or `"hybrid"`.
- Admin-managed or hybrid ownership.
- Admin routes that manage provider/policy.
- Tenant routes that consume the feature.
- Secrets and who owns them.
@@ -1,68 +0,0 @@
# Feature Integration Playbook
Use this playbook when adding a feature to the boilerplate or adapting a proprietary feature from another product.
## Goal
Make the feature understandable before implementation. A human operator and a coding agent should be able to answer where the feature lives, who owns its configuration, which flows it exposes, and how to verify it.
## Required Steps
1. Read `docs/agent-entrypoints.md`.
2. Find or create a manifest in `docs/feature-manifests/`.
3. Classify ownership:
- `tenant-owned`: tenant configures and uses it.
- `admin-managed`: admin/platform configures it; tenant only uses approved surfaces.
- `hybrid`: admin defines policy/defaults; tenant can configure local behavior.
- `system-only`: internal platform feature with no tenant-owned controls.
4. Map surfaces:
- Admin route source files and canonical admin-host runtime paths.
- Tenant route source files and canonical tenant-host runtime paths.
- Public route source files and root/web-host runtime paths.
- API route source files and canonical API-host `/v1/...` runtime paths.
- Link/form/action helpers: `adminPath`, `appPath`, `apiPath`, cross-host helpers, or `UrlUtils.getModulePath(...)` for tenant modules.
5. Map persistence:
- Prisma models.
- Existing tables reused.
- Migrations required.
- Tenant scoping fields.
6. Map configuration:
- Admin settings.
- Tenant settings.
- Environment variables.
- Secrets and their owner.
7. Map runtime:
- Request/response only.
- Queue-backed.
- Worker-backed.
- Browser-backed.
8. Map controls:
- Permissions.
- Audit events.
- Billing or usage limits.
9. Define UAT:
- Operator-visible checks.
- Negative checks for forbidden access.
- Secret exposure checks if providers are involved.
## Implementation Rules
- Do not expose provider secrets through tenant loaders, API responses, client bundles or logs.
- Do not add sidebar/nav entries without stable UI IDs.
- Do not add new root UI primitives without updating `docs/ui-inventory/components.json`.
- Do not add worker behavior without declaring queues and jobs in the manifest.
- Do not add admin-managed tenant behavior without admin permissions and audit events.
- Keep proprietary feature logic behind explicit module boundaries.
- Do not hard-code legacy runtime paths such as `/admin/...`, `/app/...`, or `/api/v1/...` outside tests that explicitly cover legacy redirects.
- Do not ship visible UI text without locale keys and `pnpm run verify:i18n`.
## Done Criteria
- Manifest updated and valid.
- Routes and surfaces match the manifest.
- Permissions are enforced on admin/API/tenant surfaces.
- Tenant-scope negative tests cover forbidden reads and mutations.
- Route helpers and runtime host ownership are tested for new navigation.
- i18n and deploy/static verifiers relevant to the change have run.
- Required worker queues/jobs exist or are explicitly deferred.
- UAT checks pass or are marked as deferred with a reason.
@@ -1,6 +1,7 @@
# Foundation Boundary Playbook
Use this when moving feature logic into the reusable boilerplate layer or when touching audit, idempotency, flags, permissions, billing usage, or notifications.
Use this when moving feature logic into HiveGrid's shared foundation or when touching audit,
idempotency, flags, permissions, billing usage, or notifications.
## Ownership Rules
@@ -20,5 +21,6 @@ Use this when moving feature logic into the reusable boilerplate layer or when t
## Done Criteria
- Add or update focused tests in the owning package.
- Update feature manifests when a feature changes ownership, billing, provider, worker, or admin-managed behavior.
- Update the owning ticket doc and architecture decision when ownership, billing, provider, worker,
or admin-managed behavior changes.
- Run `pnpm run test:foundation`, the affected package tests, and the app-level route tests for changed runtimes.
@@ -1,62 +0,0 @@
# MVP Intake Playbook
Use this before adapting an existing MVP onto this boilerplate.
## Purpose
Prevent agents from copying product code blindly. The MVP must first be decomposed into flows, roles, data, providers, ownership and runtime behavior.
## Intake Checklist
Capture the following before implementation:
- Product summary: what the MVP does in one paragraph.
- Primary user roles.
- Admin/operator roles.
- Tenant roles.
- Critical user flows.
- Data objects and ownership.
- External providers.
- Secrets and credentials.
- Background jobs.
- Browser automation or long-running work.
- Billing or usage limits.
- Existing UI surfaces.
- Must-keep behavior.
- Behavior that should become plugin-only.
- Behavior that should be removed.
## Flow Mapping
For every flow, record:
- Entry point.
- Actor.
- Preconditions.
- Data read.
- Data written.
- Provider calls.
- Sync versus async behavior.
- Success state.
- Failure state.
- UAT check.
## Boilerplate Mapping
Map each flow into:
- `apps/web/app/routes/admin*` for admin/platform management files; runtime links must use `adminPath` or admin-host helpers.
- `apps/web/app/routes/app.$tenant*` for tenant-facing usage files; runtime links must use `appPath`, `UrlUtils.getModulePath(...)`, or an equivalent host-aware wrapper.
- `apps/api/src/app.ts` under `/v1` for canonical public/service APIs and webhooks. If a `/v1` route temporarily proxies a web `internal/api` handler, record `apps/api` as the external route owner and the web handler as the temporary implementation owner until extraction lands.
- `apps/web/app/modules/<feature>` for feature-owned application logic.
- `apps/worker` and `packages/queue` for async jobs.
- `docs/feature-manifests/<feature>.json` for the integration contract.
## Output Required From Agent
Before coding, the agent should produce:
- A short MVP decomposition.
- A feature manifest draft or update.
- A list of unknowns that block safe implementation.
- An implementation plan tied to the manifest.
@@ -12,11 +12,11 @@ Use this when a feature performs slow, retryable, external, scheduled, browser-b
- Work should continue after a user navigates away.
- Usage metering or cleanup must be reliable.
## Required Manifest Entries
## Required ticket contract
The feature manifest must declare:
The owning ticket doc must declare:
- `integration.workers.required`.
- Whether a worker is required.
- Queue names from `packages/queue/src/names.ts`.
- Job names from `packages/queue/src/payloads.ts`.
- Notes about retries, idempotency and cleanup.
@@ -31,7 +31,8 @@ The feature manifest must declare:
- Jobs should be idempotent or have explicit duplicate protection.
- Browser jobs must enforce admin-owned navigation policy.
- Failures should be visible to the initiating user or admin.
- AI/browser-backed features use `hivegrid.ai-chatbot` and `hivegrid.browser-automation` unless a manifest explicitly justifies a new queue.
- Browser-backed features use the existing queue contracts unless the ticket explicitly approves a
new queue.
## Browser-Backed Work