@comet/agent-features 9.0.0-canary-20260527154746

package/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2023, Vivid Planet Software GmbH
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@comet/agent-features",
+  "version": "9.0.0-canary-20260527154746",
+  "description": "Agent features (skills and rules) for Comet projects",
+  "repository": {
+    "directory": "packages/agent-features",
+    "type": "git",
+    "url": "https://github.com/vivid-planet/comet"
+  },
+  "license": "BSD-2-Clause",
+  "files": [
+    "skills/**",
+    "rules/**"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}

package/rules/coding-guidelines/api-nestjs.instructions.md

@@ -0,0 +1,107 @@
+---
+description: NestJS service/controller layering, MikroORM, GraphQL, ACL
+applyTo: "**/api/**/*.ts"
+paths:
+    - "**/api/**/*.ts"
+globs:
+    - "**/api/**/*.ts"
+alwaysApply: false
+---
+
+# API (NestJS / MikroORM / GraphQL) Rules
+
+## Layers
+
+- **Controller / Resolver** = HTTP or GraphQL layer only. Thin: translate input, delegate to services, translate output.
+- **Service** = business logic. Must be decoupled from the transport layer:
+    - Do not accept GraphQL `InputType`s directly — accept plain objects / entities.
+    - Prefer passing the entire **entity** over passing just an ID (avoids re-fetching and ID-vs-object confusion).
+    - Services must be unit-testable and reusable from console jobs.
+- Don't create a service just for pass-through methods. Introduce one only when business logic is reused or when the controller/resolver becomes messy.
+- Utility files are fine if they are **pure, stateless functions**. They must not consume other services or repositories. Name them specifically — no generic `utils/` catch-all folders.
+
+## Access control (ACL)
+
+- Put ACL logic in a dedicated service (e.g. `products.acl.service.ts`) or inline in the controller/resolver for per-action checks.
+- **Never** perform ACL checks inside shared business services — console jobs run without a user and would either fail or accidentally double-check.
+- ACL logic must have unit tests.
+
+## Dependency injection & config
+
+- Use **constructor-based** injection. Property-based injection only when technically required.
+- Do **not** read `process.env` inside services/controllers. It's untestable, unvalidated, and uncentralized. Exception: app entry points (`main.ts`, `bootstrap.ts`).
+
+## Logging
+
+- By default log **warnings and errors only**. Put debug / info / trace behind a flag or env-configured toggle. Logs cost money in Kubernetes — see [kubernetes.instructions.md](kubernetes.instructions.md).
+- Use the built-in [NestJS Logger](https://docs.nestjs.com/techniques/logger).
+
+## MikroORM
+
+- Inject `EntityManager` directly. Do **not** inject repositories via `@InjectRepository` / `EntityRepository` — repositories are thin wrappers and add no value while complicating DI.
+
+    ```ts
+    // Good
+    constructor(private readonly entityManager: EntityManager) {}
+
+    async product(id: string) { return this.entityManager.findOneOrFail(Product, id); }
+    ```
+
+- Prefer `entityManager.create(Entity, data)` over `new Entity()` — `create` forces a complete data object.
+- Down migrations are not required. Use `throw new Error("Unsupported")` in the `down` method. Issues are fixed forward via new deployments, never rollbacks.
+
+## Entity column types
+
+- IDs: `type: "uuid"` (see [postgresql.instructions.md](postgresql.instructions.md)).
+- Strings: always `columnType: "text"` — never `varchar(n)`.
+- JSON: prefer `jsonb` over `json`.
+- Timestamps: `columnType: "timestamp with time zone"`.
+
+## DB defaults
+
+Avoid DB-level defaults — they aren't available before insert and falsify the entity's TS types. Set the default in TS instead.
+
+```ts
+// Bad
+@Property({ default: false })
+@Field()
+visible: boolean;
+
+// Good (GraphQL field — also provide a default in the InputType)
+@Property()
+@Field()
+visible: boolean;
+
+// Good (non-GraphQL property)
+@Property()
+visible: boolean = false;
+```
+
+Exception: the upsert pattern may additionally use `defaultRaw`/`onUpdate` as a fallback, on top of the TS default.
+
+## GraphQL
+
+### GraphQL enums
+
+- Keys **must equal** values; both use PascalCase — not lowercase, not SCREAMING_CASE. This is **different from TS-only enums** in [typescript.instructions.md](typescript.instructions.md).
+
+    ```ts
+    enum Category {
+        Main = "Main",
+        Secondary = "Secondary",
+    }
+    ```
+
+    Reason: Admin and Site consume the GraphQL schema (which exposes keys). If keys and values diverge, the API gets the wrong value at runtime.
+
+### Int vs Float
+
+TypeScript has only one `number`. Be explicit in GraphQL — otherwise Float (less strict) is chosen:
+
+```ts
+@Field(() => Int)
+position: number;
+
+@Field(() => Float)
+price: number;
+```

package/rules/coding-guidelines/cdn.instructions.md

@@ -0,0 +1,24 @@
+---
+description: Cache-Control header policy for GET routes (Site and API)
+applyTo: "**/api/**/*.controller.ts,**/api/**/*.resolver.ts,**/site/**/route.ts,**/site/**/next.config.js,**/site/**/next.config.ts,**/site/**/next.config.mjs"
+paths:
+    - "**/api/**/*.controller.ts"
+    - "**/api/**/*.resolver.ts"
+    - "**/site/**/route.ts"
+    - "**/site/**/next.config.{js,ts,mjs}"
+globs:
+    - "**/api/**/*.controller.ts"
+    - "**/api/**/*.resolver.ts"
+    - "**/site/**/route.ts"
+    - "**/site/**/next.config.{js,ts,mjs}"
+alwaysApply: false
+---
+
+# CDN / Caching Rules
+
+- Cache behavior is **controlled by the origin**. Never rely on CDN defaults.
+- Every GET response (Site and API) must set an explicit `Cache-Control` header.
+- Pick the TTL deliberately for the content:
+    - Static assets with cache-busting hashes → long TTL with `immutable`.
+    - API responses → short TTL, or `no-store` when the response is per-user / sensitive.
+- In Comet, all built-in routes already set `Cache-Control` — if you add a custom route/handler, you are responsible for setting it too.

package/rules/coding-guidelines/general.instructions.md

@@ -0,0 +1,30 @@
+---
+description: Language-agnostic naming, control-flow, and comment rules
+applyTo: "**/*.ts,**/*.tsx,**/*.js,**/*.jsx,**/*.mjs,**/*.cjs"
+paths:
+    - "**/*.{ts,tsx,js,jsx,mjs,cjs}"
+globs:
+    - "**/*.{ts,tsx,js,jsx,mjs,cjs}"
+alwaysApply: false
+---
+
+# General Rules (all languages)
+
+## Naming
+
+- Use descriptive names. A reader should understand intent without reading the implementation or a comment.
+- Prefer descriptive identifiers over explanatory comments — comments drift out of sync with the code.
+- Boolean variables must read as booleans: prefix with `is` / `has` / `should` (exceptions: well-known flags like `loading`, `disabled`).
+- Name booleans in the **affirmative**: `isComplete`, not `isNotComplete`. Negate at the use site with `!`.
+- Do **not** use abbreviations. Exceptions: widely-known protocols/acronyms (HTML, CSS, TCP, API, SSO…) and names dictated by third parties.
+- When an acronym appears in PascalCase / camelCase, treat it like a word: `GuiController`, `UiElement` — not `GUIController` / `UIElement`.
+
+## Control flow
+
+- **Never use exceptions for control flow.** Exceptions signal _exceptional_ situations; using them for expected branches hides real failures. Check preconditions explicitly (`if (!(await exists(id))) return undefined;`) instead of wrapping a `findOrFail` in try/catch.
+
+## Comments
+
+- Default to writing no comments. Only add a comment when the _why_ is non-obvious (hidden constraint, workaround, surprising invariant).
+- Never write comments that restate _what_ the code does — the names should do that.
+- Never reference the current task, ticket, or PR in comments — that context belongs in the PR description and rots in code.

package/rules/coding-guidelines/git.instructions.md

@@ -0,0 +1,37 @@
+---
+description: Git, commit, PR, and changeset conventions for this repo
+applyTo: "**"
+alwaysApply: false
+---
+
+# Git Rules
+
+## Pull requests
+
+- One PR per change (feature, fix, or refactor). Never combine unrelated tasks (e.g. bugfix + new feature) in one PR.
+- Do **not** include an unrelated bugfix in a feature PR, even as a separate commit. Open a follow-up PR instead.
+- Changes to `api`, `admin`, and `site` in the same PR should **not** be split into separate commits.
+- Keep PRs as small as possible. Avoid unnecessary new dependencies.
+- If the `main` pipeline is red, do not merge anything that does not contribute to fixing it.
+
+## Commits
+
+- Write commit messages in English, in the imperative, starting with a capital letter: `Add margin to footer` (not `Added margin` or `fix`).
+- Explain **what** and **why**, not **how**: `Add margin to nav items to prevent them from overlapping the logo`.
+- Never use vague messages like `fix`, `polish`, `wip`, `another try` in the final history — clean them up before merging.
+- Commits should be **atomic**: each commit leaves the code in a runnable state.
+- Prefer multiple small commits split by logical change (e.g. separate docs from feature work).
+- Exception: codemod / CRUD-generator output belongs in its own commit so reviewers can skip it.
+- Multi-line commit messages are preferred over MR-description-only explanations — the info stays in Git and shows up in IDE tools.
+
+## Branches & merging
+
+- Trunk-based development — PRs target `main` (minor/patch) or `next` (breaking).
+- Squash-merge is the default. If commit history is messy it **must** be squashed.
+- Feature branches (name prefix `feature/…`) are protected — resolve conflicts by merging main into a new branch and opening a fresh MR; never squash-merge a feature branch.
+- Cherry-picking into production is only allowed for commits already on `main`.
+
+## Review etiquette
+
+- Reviewers resolve concerns (except obvious typos). A PR merges only when all concerns are resolved and all reviewers approved.
+- `OPT:` / `Note:` / `Nit:` prefix optional suggestions.

package/rules/coding-guidelines/kubernetes.instructions.md

@@ -0,0 +1,59 @@
+---
+description: CronJob intervals, environments, replicas, resource requests/limits
+applyTo: "**/*.yaml,**/*.yml,**/helm/**,**/k8s/**"
+paths:
+    - "**/*.{yaml,yml}"
+    - "**/helm/**"
+    - "**/k8s/**"
+globs:
+    - "**/*.{yaml,yml}"
+    - "**/helm/**"
+    - "**/k8s/**"
+alwaysApply: false
+---
+
+# Kubernetes Rules
+
+## CronJobs
+
+- **Minimum interval: 10 minutes.** Shorter crons are not worth it — cold-start overhead dwarfs the resource savings.
+- For anything more frequent, deploy a long-running process with reduced resources instead.
+
+## Logging
+
+- Logging has real cost in k8s. Default to warnings/errors; make debug/info/trace toggleable via env var or flag. See also [api-nestjs.instructions.md](api-nestjs.instructions.md#logging).
+
+## Environments
+
+| Env       | Deploy                                 | Lifetime                                    | Notes                                                                       |
+| --------- | -------------------------------------- | ------------------------------------------- | --------------------------------------------------------------------------- |
+| `dev`     | Auto from `main`/`master`              | Deleted after 12 h of no deploy (data kept) | Integration canary — if pipeline is red, **nothing** merges except the fix. |
+| `test`    | Manual push, no review required        | Deleted after 7 d of no deploy (data kept)  | Internal demos / WIP features.                                              |
+| `staging` | Only `main`/`master` may be reset here | Permanent                                   | Customer acceptance; basis for prod.                                        |
+| `prod`    | Manual deploy from `staging`           | Permanent                                   | Only cherry-pick commits already on `main`.                                 |
+
+## Replicas
+
+- **Non-prod**: 1 replica — optimize for cost; brief interruptions are acceptable.
+- **Prod**: ≥2 replicas — must survive cluster-autoscaler and node upgrades.
+- Consequence: every microservice must be **stateless** so multiple replicas can run concurrently.
+
+## Resources (requests / limits)
+
+- Never over-commit memory: `memory.limit == memory.request`.
+- Do **not** set a CPU limit below 2 on Node.js services. Node is single-threaded, but the second core lets GC and k8s overhead run off the main thread.
+- `cpu.request` = CPU at average load. `memory.request` = RAM at average load + safety margin.
+
+Example:
+
+```yaml
+resources:
+    requests:
+        cpu: 50m
+        memory: 512Mi
+    limits:
+        cpu: 2
+        memory: 512Mi
+```
+
+- CPU overrun → throttled. Memory overrun → OOM-killed (exit 137). Pods are scheduled based on requests, not limits.

package/rules/coding-guidelines/libraries.instructions.md

@@ -0,0 +1,34 @@
+---
+description: Criteria for adding or replacing npm packages
+applyTo: "**/package.json"
+paths:
+    - "**/package.json"
+globs:
+    - "**/package.json"
+alwaysApply: false
+---
+
+# Libraries & Techniques Rules
+
+## Before adding a dependency
+
+- Check if there is already a go-to solution in the repo (e.g. Swiper for sliders, MUI for admin UI, Emotion/styled-components for styling). Use it instead of introducing a parallel library.
+- For "large" decisions (new paradigms like RxJS, new ORM, new state lib), do **not** decide inside a single project — coordinate with the architects first.
+- Small, non-invasive utilities (e.g. `clsx`) can be added without coordination, but the checks below still apply.
+
+## Evaluation checklist for a new npm package
+
+Before adding, verify:
+
+- **Maintenance**: recent releases, regular commits on default branch, issues getting attention.
+- **Longevity**: how long has it existed, multiple independent maintainers.
+- **Compatibility**: works with our stack (React/Next/Nest/MikroORM/TS versions in use).
+- **Bundle impact** (frontend): check [bundlephobia.com](https://bundlephobia.com/). Prefer tree-shakeable packages.
+- **Vulnerabilities**: check [security.snyk.io](https://security.snyk.io/) for known CVEs.
+- **License**: must be a recognized open-source license compatible with the product.
+
+If a package fails any of these, either pick another or flag it explicitly in the PR description with justification.
+
+## Duplication risk
+
+Do not introduce a second library that overlaps with an existing one (e.g. a different date-picker when one already exists). Consolidate instead.

package/rules/coding-guidelines/naming.instructions.md

@@ -0,0 +1,39 @@
+---
+description: File, folder, DB, and branch naming conventions across api/admin/site
+applyTo: "**/*.ts,**/*.tsx,**/*.js,**/*.jsx,**/*.sql"
+paths:
+    - "**/*.{ts,tsx,js,jsx}"
+    - "**/*.sql"
+globs:
+    - "**/*.{ts,tsx,js,jsx}"
+    - "**/*.sql"
+alwaysApply: false
+---
+
+# Naming Conventions
+
+## Files and folders
+
+| Layer                 | Folder case                        | File case                                                                                                                                     |
+| --------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| **API** (NestJS)      | `kebab-case` (e.g. `page-tree/`)   | `kebab-case` with dot segments (e.g. `page-tree.service.ts`, `page-tree.module.ts`)                                                           |
+| **Admin** (React/MUI) | `camelCase` (e.g. `pageTree/`)     | `PascalCase.tsx` for components (`DashboardPage.tsx`); `camelCase.ts` for hooks/utils (`useUser.ts`)                                          |
+| **Site** (Next.js)    | `camelCase` (e.g. `contentScope/`) | `PascalCase.tsx` for components; `camelCase.ts` for hooks/utils; **exception**: Next.js route files stay lowercase (`page.tsx`, `layout.tsx`) |
+
+## Database / infra
+
+- Database name: `db_<project>_<env>` (e.g. `db_myproject_dev`).
+- DB user: `<project>_<env>` (e.g. `myproject_dev`).
+- Entity names: singular, PascalCase (e.g. `Product`, not `Products` or `product`).
+- Kubernetes namespaces / releases: `<project>-<env>` (e.g. `myproject-prod`).
+
+## Git
+
+- Standard long-lived branches: `main`, `staging`, optionally `test`.
+- Feature branches: must start with `feature/` to receive GitLab branch protection.
+
+## Consistency with other rules
+
+- TypeScript-specific naming (enums, types) → [typescript.instructions.md](typescript.instructions.md).
+- React component/prop/state naming → [react.instructions.md](react.instructions.md).
+- Boolean, affirmative, no-abbreviation rules → [general.instructions.md](general.instructions.md).

package/rules/coding-guidelines/postgresql.instructions.md

@@ -0,0 +1,40 @@
+---
+description: UUID IDs, column types, forward-only migrations, DB defaults
+applyTo: "**/*.entity.ts,**/entities/**/*.ts,**/migrations/**/*.ts,**/*.sql"
+paths:
+    - "**/*.entity.ts"
+    - "**/entities/**/*.ts"
+    - "**/migrations/**/*.ts"
+    - "**/*.sql"
+globs:
+    - "**/*.entity.ts"
+    - "**/entities/**/*.ts"
+    - "**/migrations/**/*.ts"
+    - "**/*.sql"
+alwaysApply: false
+---
+
+# PostgreSQL Rules
+
+## IDs
+
+- Use **UUIDs** for primary keys, not auto-incrementing integers.
+    - Sequential IDs leak counts and invite enumeration attacks (`/users/1` → `/users/2`).
+    - UUIDs can be generated on the client before insert (used by page-tree documents).
+    - UUIDs let data migrate between environments without ID collisions.
+
+## Column types
+
+See [api-nestjs.instructions.md](api-nestjs.instructions.md#entity-column-types) for the full list used with MikroORM:
+
+- Strings → `columnType: "text"` (never `varchar(n)`).
+- JSON → `jsonb`, not `json`.
+- Timestamps → `columnType: "timestamp with time zone"`.
+
+## Migrations
+
+- Forward-only. Do not implement `down` migrations — `throw new Error("Unsupported")` is the standard. Problems get fixed by the next deploy, not rolled back.
+
+## DB defaults
+
+- Avoid DB-level defaults on columns exposed via the entity — they break the entity's TS types and aren't available before insert. Use TS-level defaults instead. Exception: upsert pattern, see [api-nestjs.instructions.md](api-nestjs.instructions.md#db-defaults).

package/rules/coding-guidelines/react.instructions.md

@@ -0,0 +1,102 @@
+---
+description: React component, prop, state, fragment, and anti-pattern rules
+applyTo: "**/*.ts,**/*.tsx"
+paths:
+    - "**/*.{ts,tsx}"
+globs:
+    - "**/*.{ts,tsx}"
+alwaysApply: false
+---
+
+# React Rules
+
+## General
+
+- Function components only — no class components.
+- Always write JSX. `React.createElement` is only for app initialization.
+- Children are typed via `PropsWithChildren`, not an explicit `children: ReactNode` field.
+- Inject services / API clients via **Context**, not module-level singletons.
+- Folder structure: group by **feature/module**, not by type. Move things until it feels right; avoid top-level `components/`, `hooks/`, `utils/` dumping grounds.
+- One "logical component" per file. Multiple sub-components in the same file are fine for structure/styling when they support the main export.
+
+## Naming
+
+- Components: **PascalCase**. Instances: **camelCase**. Import name must match the component name.
+- File name must match the component name (`Footer.tsx` exports `Footer`). Exception: a file exporting multiple components.
+- Prefer **meaningful file names** even inside a descriptive folder: `clients/ClientsTable.tsx`, not `clients/Table.tsx`.
+- Private sibling files use the documented suffixes: `ClientsTable.sc.ts` (styled components), `ClientsTable.gql.ts` (GraphQL). **Never import `.sc.ts` / `.gql.ts` from another component.**
+
+## Props
+
+- Props are **camelCase**.
+- Do not reuse DOM-attribute names (`className`, `hidden`, …) as custom-semantic props — pick a non-conflicting name (e.g. `variant`).
+- Boolean props are optional (`hidden?: boolean`) with no default — they're falsy by default.
+- When setting a boolean prop to `true`, omit the value: `<Foo hidden />`, not `<Foo hidden={true} />`.
+
+## State
+
+- `useState` pairs are `[value, setValue]` in camelCase: `const [userName, setUserName] = useState()`.
+
+## Performance pitfalls
+
+- **Never** define components, styled components, or stable helper functions _inside_ another component — they're re-created on every render. Hoist them to module scope.
+
+    ```tsx
+    // Bad
+    const Foo = () => {
+        const Wrapper = styled.div`…`;      // recreated every render
+        const sortJobs = (a, b) => …;       // ditto
+        return <Wrapper>…</Wrapper>;
+    };
+
+    // Good
+    const Wrapper = styled.div`…`;
+    const sortJobs = (a, b) => …;
+    const Foo = () => <Wrapper>…</Wrapper>;
+    ```
+
+- Never use the array `index` as a React `key`. Use a stable id from the item (`todo.id`).
+
+## Conditional rendering
+
+- Do **not** use `cond && <X />` when `cond` is a number — React renders `0`. Compare explicitly (`arr.length > 0 && …`) or use a ternary (`arr.length ? <X /> : null`).
+
+## SVGs
+
+- Use `<svg><use href="/icon.svg#id" /></svg>` over importing SVGs as components. See [styling.instructions.md](styling.instructions.md#svgs).
+
+## GraphQL — colocate fragments
+
+A component that consumes GraphQL data must define its own fragment and be typed by that fragment. The parent query spreads the fragment. This way the child isn't coupled to the parent's query shape.
+
+```tsx
+// DisplayName.tsx
+export const displayNameFragment = gql`
+    fragment DisplayName on User {
+        firstName
+        lastName
+    }
+`;
+
+function DisplayName({ user }: { user: GQLDisplayNameFragment }) {
+    return (
+        <>
+            {user.firstName} {user.lastName}
+        </>
+    );
+}
+
+// UserDetail.tsx
+const userDetailQuery = gql`
+    query UserDetail($id: ID!) {
+        user(id: $id) {
+            ...DisplayName
+        }
+    }
+    ${displayNameFragment}
+`;
+```
+
+## General style
+
+- Follow the official [React docs](https://react.dev/) for everything not covered here.

package/rules/coding-guidelines/security.instructions.md

@@ -0,0 +1,44 @@
+---
+description: Security-by-design, privacy, authorization, defense-in-depth principles
+applyTo: "**"
+alwaysApply: false
+---
+
+# Secure Software Development Rules
+
+Apply these when designing features, reviewing diffs, or writing validation/auth code. They are guidelines, not absolutes — reason about them explicitly rather than skipping them.
+
+## Security by design
+
+- Validate input as precisely as possible. Prefer `IsUrl`, `IsEmail`, `IsUUID`, etc. over `IsString`. Narrow validators limit the blast radius of downstream bugs (e.g. XSS).
+- Canonicalize before comparing: lowercase emails, normalize URL trailing slashes / default ports, etc. — prevents duplicate accounts and Allow/Deny list bypasses.
+- Generate random values only via crypto-secure APIs (`node:crypto`). Never use `Math.random` for tokens, IDs, secrets, or nonces.
+
+## Privacy by design
+
+- Only persist data that is actually needed. Plan deletion alongside creation (e.g. auto-delete contact requests after retention period).
+- Default settings should be the privacy-friendly option.
+- Avoid leaking account existence in flows like "forgot password": respond the same way whether the email is registered or not.
+
+## Authorization
+
+- **Least privilege**: users and services start with zero rights; grant only what is necessary. Never build an "allow everything then deny" model.
+- **Complete mediation**: check authorization on every access, not once per session.
+- **Fail-secure**: deny by default. If a rule does not explicitly grant access, access is denied. Use DB transactions to avoid partial writes on failure.
+- ACL logic belongs in a dedicated ACL service or inline in the controller/resolver — never in shared services (which also run from console jobs without an authenticated user). See [api-nestjs.instructions.md](api-nestjs.instructions.md).
+
+## Defense in depth
+
+- Combine mechanisms (e.g. IP allow-list **and** auth **and** rate limiting). One layer is not enough.
+
+## Keep it simple
+
+- Security relies on understandability and testability. Simpler designs are more secure designs. Resist clever schemes.
+
+## Don't roll your own crypto / auth
+
+- Security-sensitive primitives (hashing, signing, auth flows, session handling) must use vetted libraries or Comet's built-in tools. No obscurity-based schemes.
+
+## Admin / public separation
+
+- Administrative interfaces must be separated from public ones. Site-to-API calls without user auth go through the BFF, not directly to the API.

package/rules/coding-guidelines/styling.instructions.md

@@ -0,0 +1,50 @@
+---
+description: Theme usage, Emotion/styled-components, responsive, SVG handling
+applyTo: "**/*.tsx,**/*.sc.ts,**/*.css,**/*.scss"
+paths:
+    - "**/*.tsx"
+    - "**/*.sc.ts"
+    - "**/*.{css,scss}"
+globs:
+    - "**/*.tsx"
+    - "**/*.sc.ts"
+    - "**/*.{css,scss}"
+alwaysApply: false
+---
+
+# Styling / CSS Rules
+
+## Theme
+
+- Styling decisions go through the theme (colors, typography, buttons, spacing, breakpoints, easings). Do **not** hard-code values in components when the theme already defines them.
+- Colors: use basic tokens (`primary`, `grey`, …) when the use is generic; define context-specific tokens (`colorUiLabel`, `colorUiLabelHover`) only when a name has real semantic meaning. Don't invent context tokens that are used once.
+- Buttons / form elements: define granular tokens (`primaryBg`, `primaryBgHover`, `primaryBorder`, `primaryHeightDesktop`, …) so the theme is reusable across apps.
+- Typography: define as CSS-in-JS helpers returning `css\`…\``blocks, including media-query overrides and an optional`disableMargin` parameter.
+- Spacing: split into **dynamic** (responsive scale keyed by breakpoint) and **static** (single value) tokens.
+
+## Where styles live
+
+- **No inline `style={{ … }}`.** Use Emotion / styled-components. Name the styled component after its semantic role (`DeleteButton`, not `StyledIconButton`).
+- Keep list-level layout (flex/grid/wrap) on the list container, not on item blocks. When the item needs sizing, wrap it in an `Item` inside the list rather than styling the block itself.
+- When a component gets complex, extract styles to a `*.sc.ts` sibling file (and GraphQL to `*.gql.ts`). Those files are **private** to the component — do not import them elsewhere.
+
+## CSS layout
+
+- Use CSS Grid and Flexbox for alignment — but only when layout actually requires them. Do not blanket `display: flex` every `div`.
+
+## Browser support
+
+- Verify features via [caniuse.com](https://caniuse.com) against **All Users / Europe**.
+- **Site / frontend**: ≥93% usage → free to use. 90–93% → only if basic functionality still works without the feature; minor visual/behavioral degradation is acceptable. Below that → check with a stylist.
+- **Admin**: anything supported by current Chrome, Firefox, Safari is fair game.
+
+## Responsive
+
+- Mobile-first. Write the mobile layout first, then add breakpoint overrides upward.
+- For readability, put a blank line before every nested selector / media query inside a styled block.
+
+## SVGs
+
+- Prefer `<svg><use href="/icon.svg#id" /></svg>` — keeps SVGs out of the JS bundle and still allows `currentColor` theming.
+- Do **not** import SVGs as React components (`import Icon from "./icon.svg"` → `<Icon />`) for production icons — they inflate the bundle.
+- Do **not** use `<img src="icon.svg">` when the icon needs to be styled (e.g. color changes), since `<img>` cannot be manipulated.