@bitakit/cli 0.2.4 → 0.2.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AGENTS.md ADDED
@@ -0,0 +1,32 @@
1
+ # @bitakit/cli — guide for agents
2
+
3
+ > For agents building an app with this package (it ships in `node_modules/@bitakit/cli`). To
4
+ > change the package itself, follow the repository's own AGENTS.md instead.
5
+
6
+ The `bitakit` command. It scaffolds plugins and contributions, regenerates the wiring and
7
+ checks a project. It also ships the `bitakit-app-development` skill, which `create-app` and
8
+ `bitakit init` install into `.agents/skills/` and `.claude/skills/`: read that skill first.
9
+
10
+ ## Commands agents use
11
+
12
+ | Command | Does |
13
+ | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
14
+ | `npx bitakit add plugin <name>` | A plugin with a page and a navigation link (`--example`, `--minimal`) |
15
+ | `npx bitakit add <kind> <plugin>/<name>` | `action`, `service`, `page`, `interceptor`, `config`, `slot`, `slot-definition`, `dialog`, `provider` |
16
+ | `npx bitakit add events\|settings\|settings-page <plugin>` | The plugin's single file of that kind |
17
+ | `npx bitakit add layout <family>[/<variant>]` | A candidate for `layout.<family>` (`--plugin <id>` for a plugin) |
18
+ | `npx bitakit add test <plugin>` | A headless test, plus the setup commands it still needs |
19
+ | `npx bitakit info --json` | Plugins, services, Actions, events, settings, pages |
20
+ | `npx bitakit slots [--json]` | Every slot, its owner, contributions and, for replaceable parts, what renders |
21
+ | `npx bitakit doctor [--json]` | Wiring, versions, routes, links, slots, replaceable parts, agent files |
22
+ | `npx bitakit check-page /<path> --json` | Opens the page headlessly and reports headings and errors (Playwright) |
23
+ | `npx bitakit init --update-agent-files` | Refreshes AGENTS.md's BitaKit block and unedited skill copies |
24
+
25
+ `add` never overwrites a file. Run `npm run typecheck` and `npx bitakit doctor` after changes;
26
+ doctor exits 1 on errors and names the fix.
27
+
28
+ ## Rules
29
+
30
+ - Replace template bodies and tutorial comments with the real implementation.
31
+ - `bitakit migrate` is the 0.1 upgrade; do not run it to tidy a current project.
32
+ - Ask before installing Playwright or test dependencies that commands print.
package/README.md CHANGED
@@ -105,6 +105,8 @@ npx bitakit add page notes/archive # ui/pages/archive.tsx → /not
105
105
  npx bitakit add interceptor notes/audit # interceptors/audit.ts
106
106
  npx bitakit add config notes/limits # configs/limits.ts → app.config.notes.limits
107
107
  npx bitakit add events notes # events.ts
108
+ npx bitakit add layout auth/split # src/layouts/auth/split.tsx → a candidate for layout.auth
109
+ npx bitakit add layout auth --plugin brand # src/plugins/brand/ui/layouts/auth.tsx
108
110
  ```
109
111
 
110
112
  The file path decides the ID; nested names such as `notes/team/invite` create
@@ -146,11 +148,17 @@ npx bitakit info [--json] # the plugins, services, actions, events and pages d
146
148
  npx bitakit slots [--json] # every slot you can fill: owner, accepts and this app's contributions
147
149
  ```
148
150
 
151
+ For a replaceable (`single`) slot, `slots` also prints which candidate renders, from the app's
152
+ files and `choose` in `bitakit.config.ts` (`renders app:split`, or `renders the default: choose
153
+ one of ...`); `--json` adds `selection: { candidates, renders, reason, choice }`. Layout files
154
+ count as candidates of `layout.<family>`. Packages can add candidates at runtime.
155
+
149
156
  Doctor checks package versions, duplicate copies of `@bitakit/core`, the config wrapper and
150
157
  provider wiring, scripts that still force Webpack or `foundation-generate`, ignored generated
151
158
  files, plugin pages and links no route reaches, colliding service names, `requires` entries that
152
- name nothing, plugin dependency cycles, missing package styles, deprecated layouts and agent files
153
- that are out of sync, and prints a fix for each problem.
159
+ name nothing, plugin dependency cycles, missing package styles, deprecated layouts, replaceable
160
+ parts without a decision (several candidates in the app's files, or `choose` entries for unknown
161
+ or non-single slots) and agent files that are out of sync, and prints a fix for each problem.
154
162
 
155
163
  The `requires` check reads the string literals of `requires` in services, actions, interceptors
156
164
  and in `export const requires` of provider files. A name must be a service ID, an `exposeAs`
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bitakit/cli",
3
- "version": "0.2.4",
3
+ "version": "0.2.6",
4
4
  "description": "BitaKit project commands: add plugins and contributions, check a project with doctor.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -14,6 +14,7 @@
14
14
  "src",
15
15
  "skills",
16
16
  "README.md",
17
+ "AGENTS.md",
17
18
  "LICENSE"
18
19
  ],
19
20
  "engines": {
@@ -23,8 +24,8 @@
23
24
  "test": "node --test tests/*.test.mjs"
24
25
  },
25
26
  "dependencies": {
26
- "@bitakit/core": "^0.2.2",
27
- "@bitakit/discovery": "^0.2.2",
27
+ "@bitakit/core": "^0.2.5",
28
+ "@bitakit/discovery": "^0.2.3",
28
29
  "commander": "15.0.0",
29
30
  "typescript": "^5.9.3"
30
31
  },
@@ -75,15 +75,20 @@ save a recipe with a title and ingredients" works the same way.
75
75
 
76
76
  ## What the skill covers
77
77
 
78
- | Task | Recipe |
79
- | ------------------------------------------------------------------------ | ----------------------------------------------------------- |
80
- | Create a plugin, a page or a sidebar link | [plugins-and-pages.md](references/plugins-and-pages.md) |
81
- | Add an Action and bind it to a button or link | [actions.md](references/actions.md) |
82
- | Keep shared state, use another plugin's service, send and receive events | [services-and-events.md](references/services-and-events.md) |
83
- | Declare a slot, render it, contribute to one | [slots.md](references/slots.md) |
84
- | Block, check or observe Actions | [interceptors.md](references/interceptors.md) |
85
- | Add a user setting | [settings.md](references/settings.md) |
86
- | Test a plugin and check it in the browser | [testing-and-preview.md](references/testing-and-preview.md) |
78
+ | Task | Recipe |
79
+ | -------------------------------------------------------------------------- | ----------------------------------------------------------- |
80
+ | Build a whole feature step by step (Bookmarks) | [worked-example.md](references/worked-example.md) |
81
+ | Create a plugin, a page or a sidebar link | [plugins-and-pages.md](references/plugins-and-pages.md) |
82
+ | Add an Action and bind it to a button or link | [actions.md](references/actions.md) |
83
+ | Keep shared state, use another plugin's service, send and receive events | [services-and-events.md](references/services-and-events.md) |
84
+ | Declare a slot, render it, contribute to one | [slots.md](references/slots.md) |
85
+ | Block, check or observe Actions | [interceptors.md](references/interceptors.md) |
86
+ | Add a user setting | [settings.md](references/settings.md) |
87
+ | Replace a layout, the frame, a 404 or error page, or another plugin's part | [layouts-and-screens.md](references/layouts-and-screens.md) |
88
+ | Load and save data through an API route | [data-and-api.md](references/data-and-api.md) |
89
+ | Avoid common mistakes; naming | [best-practices.md](references/best-practices.md) |
90
+ | Change the app's colors, fonts or theme | Theme files in the `@bitakit/shell` README |
91
+ | Test a plugin and check it in the browser | [testing-and-preview.md](references/testing-and-preview.md) |
87
92
 
88
93
  Before every change the agent reads the app's packages, runs `npx bitakit info --json`,
89
94
  `npx bitakit slots` and `npx bitakit doctor`, and checks which layout renders the place it wants
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: bitakit-app-development
3
- description: Builds and extends BitaKit apps (@bitakit/* packages, features in src/plugins/<name>/). Use when creating a BitaKit app or plugin, adding a page, Action (button, link, menu entry), service, event, setting, interceptor, slot or slot contribution, placing UI in the navigation, toolbar or header, testing a plugin, checking the result in the browser preview, or explaining how a BitaKit feature works.
3
+ description: Builds and extends BitaKit apps (@bitakit/* packages, features in src/plugins/<name>/). Use when creating a BitaKit app or plugin, adding a page, Action (button, link, menu entry), service, event, setting, interceptor, slot or slot contribution, placing UI in the navigation, toolbar or header, changing the app's colors or theme, replacing a layout or a screen such as sign-in or 404, testing a plugin, checking the result in the browser preview, or explaining how a BitaKit feature works.
4
4
  ---
5
5
 
6
6
  # BitaKit app development
@@ -20,16 +20,23 @@ minimal example and the rules that matter.
20
20
 
21
21
  | The user wants | Read |
22
22
  | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
23
+ | A whole new feature (plan, files, checks, report, step by step) | [references/worked-example.md](references/worked-example.md) |
23
24
  | A new feature, a page, or a link in the sidebar | [references/plugins-and-pages.md](references/plugins-and-pages.md) |
24
25
  | A button, link, menu entry or operation | [references/actions.md](references/actions.md) |
25
26
  | Shared state or logic, or reacting to another feature | [references/services-and-events.md](references/services-and-events.md) |
26
27
  | A place other features can extend, or UI in the header, sidebar or another feature | [references/slots.md](references/slots.md) |
28
+ | Another layout or frame, their own 404, error or sign-in page, a replaceable part | [references/layouts-and-screens.md](references/layouts-and-screens.md) |
27
29
  | A rule around Actions: block, check or observe them | [references/interceptors.md](references/interceptors.md) |
28
30
  | A user preference | [references/settings.md](references/settings.md) |
31
+ | Data that survives a reload or comes from a server or database | [references/data-and-api.md](references/data-and-api.md) |
32
+ | The app's colors, fonts or a theme file | The Theme files section of `node_modules/@bitakit/shell/README.md` |
29
33
  | Tests, the browser preview, or what to report | [references/testing-and-preview.md](references/testing-and-preview.md) |
30
34
 
31
- The examples extend the Todo sample (`create-app --sample`): `todos` owns the list and `activity`
32
- extends it. Use the user's own domain names in real code.
35
+ The recipes extend the Todo sample (`create-app --sample`): `todos` owns the list and `activity`
36
+ extends it. The worked example and the data recipe build a Bookmarks feature from scratch. Use
37
+ the user's own domain names in real code. Before the first change of a session, read
38
+ [references/best-practices.md](references/best-practices.md): the mistakes it lists are the
39
+ ones that break features quietly.
33
40
 
34
41
  ## Create a new application
35
42
 
@@ -70,33 +77,69 @@ Do this once per session, before the first change:
70
77
  3. Run `npx bitakit doctor` and fix existing errors before blaming a new change. When it reports
71
78
  agent files out of sync, such as an outdated skill, tell the user and suggest
72
79
  `npx bitakit init --update-agent-files`.
73
- 4. Read the owning plugin's files before changing them. Generated `src/bitakit.gen.*` files are
74
- evidence for types; never edit them.
80
+ 4. Read the owning plugin's files before changing them, starting with its `AGENTS.md` when it
81
+ has one. Every installed `@bitakit/*` package ships `node_modules/@bitakit/<name>/AGENTS.md`:
82
+ what it provides (IDs, slots, replaceable parts), how to extend or replace it and its rules.
83
+ Read it before using the package; its README has the details. Generated `src/bitakit.gen.*`
84
+ files are evidence for types; never edit them. Keep plugin-specific recipes with their owning
85
+ package.
75
86
  5. Before placing UI, inspect the app's selected composition: which layout frames the page (Shell
76
- `sidebar`, the default, or `navbar`; a page's `export const layout`; or `src/layouts/<name>.tsx`)
87
+ `sidebar`, the default, or `navbar`; a page's `export const layout` family; `src/layouts/`)
77
88
  and which component actually renders the slot you want. A declared slot shows nothing until an
78
89
  outlet renders it.
79
90
 
91
+ ## Choose the mechanism
92
+
93
+ Decide before writing code, and tell the user the plan in a sentence or two.
94
+
95
+ | You need | Use | File in the plugin |
96
+ | -------------------------------------------------------- | --------------------------------- | -------------------------------------------------------- |
97
+ | A screen | Page | `ui/pages/<path>.tsx` |
98
+ | Data or logic that pages, Actions and other features use | Service with a `store()` | `services/<name>.ts` |
99
+ | Something the user triggers: button, link, menu entry | Action bound with `<Action>` | `actions/<name>.ts` |
100
+ | A choice the user keeps after a reload | Setting | `settings.ts` |
101
+ | To tell other features that something happened | Event | `events.ts` |
102
+ | A place where other features can add buttons or UI | Slot and its outlet | `slots/<name>.ts` |
103
+ | Your UI in another feature's place or in the Shell | Slot contribution or Action slots | `ui/slots/<slot>.tsx` |
104
+ | Another layout, frame or screen (404, error, sign-in) | A file for its single slot | `src/layouts/<family>.tsx`, `ui/slots/screen.<name>.tsx` |
105
+ | A rule over Actions you do not own | Interceptor | `interceptors/<name>.ts` |
106
+ | Saved or server data, secrets, permission checks | API route and a service | `src/app/api/<name>/route.ts` |
107
+
80
108
  ## Implement in the owning plugin
81
109
 
82
110
  - One feature, one plugin. Create it with `npx bitakit add plugin <name>` and add files with
83
111
  `npx bitakit add <kind> <plugin>/<name>` (kinds: `action`, `service`, `page`, `interceptor`,
84
112
  `config`, `slot`, `slot-definition`, `dialog`, `provider`). `events`, `settings` and
85
- `settings-page` take only `<plugin>`; `layout <name>` is app-level; `test <plugin>` writes
113
+ `settings-page` take only `<plugin>`; `layout <family>[/<variant>]` writes `src/layouts/`
114
+ (`--plugin <id>` for a plugin's `ui/layouts/`); `test <plugin>` writes
86
115
  `tests/<plugin>.test.ts`. Existing files are never overwritten.
87
116
  - Folders are the default layout; flat files (`actions.add.ts`, or one `actions.ts` for several
88
117
  Actions) declare the same IDs and are equally fine. Follow the layout the app already uses; see
89
118
  [references/plugins-and-pages.md](references/plugins-and-pages.md#folders-or-flat-files).
90
119
  - Replace the generated template bodies and tutorial comments with the real implementation.
91
120
  - Extend a feature you do not own from your own plugin: listen to its events, fill its slots,
92
- call its services (declared with `requires`) and read its settings. Change the owner only when
93
- it must offer a new contract, such as a slot it renders, and tell the user why.
121
+ replace its parts, call its services (declared with `requires`) and read its settings. Change
122
+ the owner only when it must offer a new contract, such as a slot it renders, and tell the user
123
+ why.
124
+ - A plugin that other features build on keeps a short `AGENTS.md` in its folder: what it owns
125
+ (services, Actions, events, settings, slots and replaceable parts), how others extend or
126
+ replace it, and its rules. Update it with the contract; discovery ignores the file.
94
127
  - State lives in services, preferences in settings, operations in Actions bound to controls with
95
128
  `<Action>`. Pages and components live under `ui/` and start with `'use client'` in Next.js.
96
129
  - Use `@bitakit/ui/components` and the app's theme tokens. Keep styling to the existing
97
- components and layout utilities.
130
+ components and layout utilities. Important public UI parts should keep a few stable,
131
+ namespaced classes for intentional external CSS overrides. Reuse existing classes,
132
+ state/ARIA attributes and native hover/focus selectors; no wrapper-by-wrapper class inventory,
133
+ redundant state classes or extra styling system. Use ordinary CSS directly; no Tailwind
134
+ indirection is necessary. The central theme remains the default.
135
+ Document actual class names/states with the owning component, including a direct entry point
136
+ for portaled content.
98
137
  - Build on BitaKit's mechanisms: no own registries, event buses, settings stores or button
99
138
  state, and no edits to generated files or the framework's provider wiring.
139
+ - Habits that prevent most bugs ([references/best-practices.md](references/best-practices.md)):
140
+ return the promise from `execute`; replace store values instead of changing them; read
141
+ settings when you use them; load data in services, not components; check permissions on the
142
+ server; give every list an empty, a loading and an error state.
100
143
  - Ask before adding a dependency. Install BitaKit packages at the version the app already uses,
101
144
  for example `npm install @bitakit/app-preferences@<installed @bitakit/core version>`.
102
145
 
@@ -0,0 +1,211 @@
1
+ # Best practices and common mistakes
2
+
3
+ Each rule names the mistake agents make most often, why it breaks, and the fix. The examples use
4
+ the Bookmarks feature from [worked-example.md](worked-example.md).
5
+
6
+ ## Run operations through Actions
7
+
8
+ A service call in `onClick` loses what the Action provides: disabled and pending state, the
9
+ confirmation, success and failure messages, interceptors and keyboard shortcuts.
10
+
11
+ ```tsx
12
+ // ✗ No pending state, no confirmation, errors vanish.
13
+ <Button onClick={() => services.bookmarks.list.remove(bookmark.id)}>Remove</Button>
14
+ ```
15
+
16
+ ```tsx
17
+ // ✓ The Action owns the label, guards and messages.
18
+ <Action id="bookmarks.remove" input={bookmark.id}>
19
+ <Button variant="outline" size="sm" />
20
+ </Action>
21
+ ```
22
+
23
+ For a control that needs its own markup, use `useAction(id).props()` ([actions.md](actions.md)).
24
+
25
+ ## Read service state with a selector; do not copy it
26
+
27
+ Copying a store into React state shows stale data and renders twice.
28
+
29
+ ```tsx
30
+ // ✗ A second copy that drifts from the service.
31
+ const [bookmarks, setBookmarks] = useState<Bookmark[]>([]);
32
+ useEffect(() => setBookmarks(service?.state.get().bookmarks ?? []), [service]);
33
+ ```
34
+
35
+ ```tsx
36
+ // ✓ Re-renders only when the selected value changes; [] until the service is ready.
37
+ const bookmarks = useServiceState('bookmarks.list', (state) => state.bookmarks, []);
38
+ ```
39
+
40
+ Select the smallest value a component needs, such as `state.bookmarks.length` for a counter.
41
+
42
+ ## Replace store values; never change them in place
43
+
44
+ `state.set` is what notifies pages and Actions. Changing the current value does not.
45
+
46
+ ```ts
47
+ // ✗ Nothing re-renders; other readers see a changed array without notice.
48
+ state.get().bookmarks.push(bookmark);
49
+ ```
50
+
51
+ ```ts
52
+ // ✓ A new array, and every reader updates.
53
+ state.set((current) => ({ ...current, bookmarks: [...current.bookmarks, bookmark] }));
54
+ ```
55
+
56
+ ## Return the promise from `execute`
57
+
58
+ The Action waits for what `execute` returns. Without a return the run ends at once, the button
59
+ is not pending, and a failure becomes an unhandled rejection instead of a message.
60
+
61
+ ```ts
62
+ // ✗ Braces without return: completes immediately, errors are lost.
63
+ execute: ({ services, input }) => {
64
+ services.bookmarks.list.add(input);
65
+ },
66
+ ```
67
+
68
+ ```ts
69
+ // ✓
70
+ execute: ({ services, input }) => services.bookmarks.list.add(input),
71
+ ```
72
+
73
+ ## Read settings when you use them
74
+
75
+ A service factory runs before stored settings load, so a value read there stays at its default.
76
+
77
+ ```ts
78
+ // ✗ Always the default value.
79
+ export default defineService(({ settings }) => {
80
+ const newTab = settings.bookmarks.openInNewTab.get();
81
+ // ...
82
+ });
83
+ ```
84
+
85
+ ```ts
86
+ // ✓ Read inside the method, at call time.
87
+ open(url: string) {
88
+ window.open(url, settings.bookmarks.openInNewTab.get() ? '_blank' : '_self');
89
+ },
90
+ ```
91
+
92
+ In React, use `useSetting('bookmarks.openInNewTab').value`; in Actions, the `settings` argument.
93
+
94
+ ## Reach other features through their contracts
95
+
96
+ Importing another plugin's files ties the two folders together: removing or renaming one breaks
97
+ the other, and the import bypasses startup order and the missing-service check.
98
+
99
+ ```ts
100
+ // ✗ In src/plugins/sharing: reaches into another plugin's folder.
101
+ import list from '../../bookmarks/services/list';
102
+ ```
103
+
104
+ ```ts
105
+ // ✓ src/plugins/sharing/actions/copy-links.ts: the service by name, declared as a dependency.
106
+ import { defineAction } from '@bitakit/core';
107
+
108
+ export default defineAction({
109
+ title: 'Copy all links',
110
+ requires: ['bookmarks.list'],
111
+ execute: ({ services }) =>
112
+ navigator.clipboard.writeText(
113
+ services.bookmarks.list.state
114
+ .get()
115
+ .bookmarks.map((bookmark) => bookmark.url)
116
+ .join('\n'),
117
+ ),
118
+ });
119
+ ```
120
+
121
+ Read the state with `useServiceState`, react to `bookmarks.added` with `events.on`, and add UI
122
+ through the owner's slots. A type-only import in a test is fine.
123
+
124
+ ## Place UI with `slots`, not `groups`
125
+
126
+ `groups` is a logical label for queries; it never renders anything.
127
+
128
+ ```ts
129
+ // ✗ Appears nowhere.
130
+ defineAction({ title: 'Bookmarks', href: '/bookmarks', groups: ['navigation'] });
131
+ ```
132
+
133
+ ```ts
134
+ // ✓ Shell renders it in the navigation.
135
+ defineAction({ title: 'Bookmarks', href: '/bookmarks', slots: ['shell.navigation'] });
136
+ ```
137
+
138
+ ## Load data in services, not in components
139
+
140
+ A `fetch` in a page runs again on every visit, is not shared with Actions or other features,
141
+ and leaves loading and error handling to each component. Load in the service's `onStart`, keep
142
+ `status` and `error` in its store, and let pages render them
143
+ ([data-and-api.md](data-and-api.md)).
144
+
145
+ ## Emit your own events after the change
146
+
147
+ Only the declaring plugin emits its events, and only after its state changed, so listeners read
148
+ the new state. To react to another feature, listen to its event; to need a new one, add it in
149
+ the owner.
150
+
151
+ ```ts
152
+ // ✗ Emitted before the change, and from a plugin that does not own the event.
153
+ events.emit('bookmarks.added', { id, url });
154
+ ```
155
+
156
+ ```ts
157
+ // ✓ In the bookmarks service, after state.set(...).
158
+ events.emit('bookmarks.added', { id: bookmark.id, url: bookmark.url });
159
+ ```
160
+
161
+ ## Enforce permissions on the server
162
+
163
+ `enabled`, `visible`, `confirm` and interceptors shape the UI in the browser. Anyone can call
164
+ the API directly, so the API route checks the session and the input again.
165
+
166
+ ## Give every list its states
167
+
168
+ Show an empty state ("No bookmarks yet"), a loading placeholder (`Skeleton`) and an error with a
169
+ retry Action. A blank area looks broken.
170
+
171
+ ## Keep the generated and template code out of the result
172
+
173
+ - Never edit `src/bitakit.gen.*`; change the source file and run `npm run typecheck`.
174
+ - Replace template bodies, placeholder subtitles and tutorial comments from `bitakit add`, and
175
+ delete files the feature does not use.
176
+ - Keep one feature in one plugin folder: deleting the folder removes the feature and nothing else.
177
+
178
+ ## Replace parts through their slot, never by editing the owner
179
+
180
+ A sign-in frame, a 404 page or another plugin's card is a replaceable part (a single slot). Put
181
+ your version in your own folder and leave the owner unchanged.
182
+
183
+ ```text
184
+ ✗ Editing node_modules/@bitakit/shell or another team's plugin to change its not-found page.
185
+ ✓ src/plugins/brand/ui/slots/screen.not-found.tsx (or src/layouts/auth.tsx for a layout)
186
+ ```
187
+
188
+ Deleting your file brings the default back. With several candidates, decide in
189
+ `bitakit.config.ts` (`choose`); see [layouts-and-screens.md](layouts-and-screens.md).
190
+
191
+ ## Let a plugin introduce itself
192
+
193
+ Every installed `@bitakit/*` package ships an `AGENTS.md` with its IDs, extension points and
194
+ rules; read `node_modules/@bitakit/<name>/AGENTS.md` before using it. Give your own shared
195
+ plugins the same: a short `src/plugins/<id>/AGENTS.md` that names what the plugin owns
196
+ (services, Actions, events, settings, slots and replaceable parts), how other features extend
197
+ or replace it, and what must not change. Keep it current when the contract changes.
198
+
199
+ ## Name things after the domain
200
+
201
+ | Kind | Form | Examples |
202
+ | ------- | ------------------------------ | ------------------------------------- |
203
+ | Plugin | The feature, usually a noun | `bookmarks`, `billing`, `team` |
204
+ | Action | A verb, optionally with object | `add`, `remove`, `open`, `export-csv` |
205
+ | Service | What it holds | `list`, `feed`, `cart` |
206
+ | Event | What happened, past tense | `added`, `removed`, `changed` |
207
+ | Setting | The preference, in camelCase | `limit`, `openInNewTab` |
208
+ | Slot | Where it renders | `toolbar`, `footer`, `row.menu` |
209
+
210
+ The plugin ID prefixes every name, so `bookmarks.add` reads as a sentence; do not repeat the
211
+ plugin in the file name (`actions/add.ts`, not `actions/add-bookmark.ts`).