@eventmodelers/cli 0.0.1

package/stacks/cratis-csharp/templates/.claude/skills/build-state-change/references/patterns.md

@@ -0,0 +1,234 @@
+# Write Slice Patterns — Cratis Arc + Chronicle
+
+Complete code for state-change (write) slices. All artifacts go in a single
+`<Module>/<Feature>/<Slice>/<Slice>.cs` file (the shipped starter uses `SomeModule/SomeFeature/...` —
+match whatever the existing slices use). The example slices use no file header (match the project).
+Namespace mirrors the folders and drops any `.Features.`. The examples below use short illustrative
+names (`MyApp.Authors.Registration`); mirror your project's actual module/feature layout instead.
+
+---
+
+## 1. Concept (one per file, in the feature folder)
+
+```csharp
+// Features/Authors/AuthorId.cs
+namespace MyApp.Authors;
+
+public record AuthorId(Guid Value) : ConceptAs<Guid>(Value)
+{
+    public static readonly AuthorId NotSet = new(Guid.Empty);
+    public static implicit operator Guid(AuthorId id) => id.Value;
+    public static implicit operator AuthorId(Guid value) => new(value);
+    public static implicit operator EventSourceId(AuthorId id) => new(id.Value.ToString());
+    public static AuthorId New() => new(Guid.NewGuid());
+}
+
+// Features/Authors/AuthorName.cs
+public record AuthorName(string Value) : ConceptAs<string>(Value)
+{
+    public static readonly AuthorName NotSet = new(string.Empty);
+    public static implicit operator string(AuthorName name) => name.Value;
+    public static implicit operator AuthorName(string value) => new(value);
+}
+```
+
+---
+
+## 2. Simplest write slice — single event
+
+```csharp
+// Features/Authors/Registration/Registration.cs
+namespace MyApp.Authors.Registration;
+
+using Cratis.Arc.Commands.ModelBound;
+using Cratis.Chronicle.Events;
+
+[Command]
+public record RegisterAuthor([Key] AuthorId Id, AuthorName Name)
+{
+    public AuthorRegistered Handle() => new(Name);
+}
+
+[EventType]
+public record AuthorRegistered(AuthorName Name);
+
+public class RegisterAuthorValidator : CommandValidator<RegisterAuthor>
+{
+    public RegisterAuthorValidator() =>
+        RuleFor(c => c.Name).NotEmpty().WithMessage("Name is required").MaximumLength(100);
+}
+```
+
+The `[Key]` parameter is the event source id. With a concept that converts to `EventSourceId`, you may
+omit `[Key]` and let Arc resolve it.
+
+---
+
+## 3. Generate-and-return a new id
+
+```csharp
+[Command]
+public record RegisterAuthor(AuthorName Name)
+{
+    public (AuthorId, AuthorRegistered) Handle()
+    {
+        var id = AuthorId.New();
+        return (id, new AuthorRegistered(Name));   // id flows back as CommandResult<AuthorId>.response
+    }
+}
+```
+
+---
+
+## 4. Multiple events
+
+```csharp
+[Command]
+public record TransferFunds(AccountId FromId, AccountId ToId, decimal Amount)
+{
+    public IEnumerable<object> Handle() =>
+    [
+        new FundsWithdrawn(FromId, Amount),
+        new FundsDeposited(ToId, Amount),
+    ];
+}
+```
+
+---
+
+## 5. Injected dependency / constraint
+
+`Handle()` parameters are DI-resolved. Use for external services or constraints (e.g. uniqueness):
+
+```csharp
+[Command]
+public record OpenDebitAccount([Key] AccountId Id, string Name, OwnerId OwnerId)
+{
+    public async Task<DebitAccountOpened> Handle(IUniqueAccountConstraint constraint)
+    {
+        await constraint.Validate(Name);          // throws on violation
+        return new DebitAccountOpened(Name, OwnerId);
+    }
+}
+```
+
+---
+
+## 6. Business rule via DCB (inject a read model)
+
+When a rule depends on event-sourced state, accept the relevant read model as a `Handle()` parameter.
+Arc materializes current state from the event log and injects it. Return a `Result<,>` for a clean
+success/error contract:
+
+```csharp
+[Command]
+public record ReserveBook([Key] BookId Id, MemberId Member)
+{
+    public Result<BookReserved, ReservationError> Handle(BookAvailability availability)
+    {
+        if (availability is null || !availability.IsAvailable)
+            return ReservationError.NotAvailable;
+        return new BookReserved(Member);
+    }
+}
+
+public enum ReservationError { NotAvailable }
+```
+
+Only encode rules that appear in the slice `description` / `comments`.
+
+---
+
+## 7. Integration spec (Chronicle, full stack)
+
+`Features/Authors/Registration/when_registering/and_there_are_no_authors.cs`
+
+```csharp
+using context = MyApp.Authors.Registration.when_registering.and_there_are_no_authors.context;
+
+namespace MyApp.Authors.Registration.when_registering;
+
+[Collection(ChronicleCollection.Name)]
+public class and_there_are_no_authors(context context) : Given<context>(context)
+{
+    public class context(ChronicleOutOfProcessFixture fixture) : given.an_http_client(fixture)
+    {
+        public CommandResult<AuthorId>? Result;
+
+        async Task Because() =>
+            Result = await Client.ExecuteCommand<RegisterAuthor, AuthorId>(
+                "/api/authors/register",
+                new RegisterAuthor(AuthorId.New(), new AuthorName("John Doe")));
+    }
+
+    [Fact] void should_be_successful() => Context.Result!.IsSuccess.ShouldBeTrue();
+    [Fact] void should_have_appended_one_event() =>
+        Context.ShouldHaveTailSequenceNumber(EventSequenceNumber.First);
+    [Fact] void should_append_author_registered_event() =>
+        Context.ShouldHaveAppendedEvent<AuthorRegistered>(
+            EventSequenceNumber.First, Context.Result!.Response,
+            evt => evt.Name.Value.ShouldEqual("John Doe"));
+}
+```
+
+### Pure unit spec on `Handle()` (no I/O)
+
+```csharp
+namespace MyApp.Authors.Registration.for_RegisterAuthor;
+
+public class when_registering : Specification
+{
+    RegisterAuthor _command;
+    AuthorRegistered _event;
+
+    void Establish() => _command = new(AuthorId.New(), new AuthorName("John"));
+    void Because() => _event = _command.Handle();
+
+    [Fact] void should_carry_the_name() => _event.Name.Value.ShouldEqual("John");
+}
+```
+
+---
+
+## 8. React command UI (after `dotnet build` generated the proxy)
+
+The proxy (`RegisterAuthor.ts`) is generated **next to** `Registration.cs` (the starter's `.csproj`
+sets `CratisProxiesUseSourceFileAsOutputFile=true`), so import it from the **same folder**. Add a barrel
+`index.ts` (`export * from './AddAuthor'`) like the shipped example slice.
+
+```tsx
+// Authors/Registration/AddAuthor.tsx
+import { CommandDialog } from '@cratis/components/CommandDialog';
+import { InputTextField } from '@cratis/components/CommandForm';
+import { RegisterAuthor } from './RegisterAuthor';   // co-located generated proxy
+
+export const AddAuthor = () => (
+    <CommandDialog command={RegisterAuthor} title="Add author" okLabel="Add" cancelLabel="Cancel">
+        <InputTextField<RegisterAuthor> value={c => c.name} title="Name" />
+    </CommandDialog>
+);
+```
+
+Inline form alternative:
+
+```tsx
+const [command] = RegisterAuthor.use();
+const submit = async () => {
+    const result = await command.execute();
+    if (result.isSuccess) onSuccess(result.response);
+};
+```
+
+Never import `Dialog` from `primereact/dialog` — use the Cratis wrappers. PrimeReact CSS variables for
+colors. No `any`. Full descriptive variable names.
+
+---
+
+## Checklist
+
+- One `.cs` file, namespace without `.Features.` (no file header unless the project uses one).
+- `[Command]` with `Handle()` on the record — no handler class.
+- `[EventType]` with **no** arguments; past-tense names; no nullable fields.
+- `ConceptAs<T>` for every identity / value — no raw `Guid` / `string` in the domain.
+- `CommandValidator<T>` for validations; read-model parameter for DCB rules.
+- One spec per scenario in `slice.json`; `dotnet build` clean; specs pass.

package/stacks/cratis-csharp/templates/.claude/skills/build-state-view/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: build-state-view
+description: >
+  Implement read slices the Cratis way — a [ReadModel] record with static query methods, fed by a
+  Chronicle projection or reducer, plus the React component that renders it. Use when: (1) implementing
+  a new read slice / projection in a Cratis project, (2) a slice.json has a non-empty readModel /
+  projections / queries section, (3) the user provides a read-slice Event Modeling artifact or
+  specification and asks to implement it, (4) the user says "implement", "create", "add" a read slice,
+  read model, projection, reducer, or query in a Cratis Arc / Chronicle project.
+---
+
+# Cratis — Read Slice (State View)
+
+A read slice projects events into a queryable read model. In Cratis the path lives in **one `.cs`
+file**:
+
+```
+[ReadModel] record + static queries  →  projection or reducer  →  dotnet build  →  React
+```
+
+> **Read first:** [../_shared/cratis-conventions.md](../_shared/cratis-conventions.md). Everything
+> below assumes those rules.
+
+## Step 0 — Discover conventions
+
+Read `CLAUDE.md` and one existing read slice. Confirm the namespace root, how existing read models
+declare queries (snapshot vs observable), whether projections use model-bound attributes or
+`IProjectionFor<T>`, and the MongoDB collection wiring. Resolve slice `comments` when done (see the
+state-change skill's Step 0 for the resolve endpoint).
+
+## Step 1 — Understand the input (`slice.json` is the source of truth)
+
+| Element | What to extract |
+|---|---|
+| **Read model** | Name, fields, the key field |
+| **Source events** | Which events feed each field (projections **join events, never read models**) |
+| **Queries** | The queries to expose; whether each is snapshot or real-time (observable) |
+| **Specifications** | Each scenario → an executable spec proving the projection result |
+
+If a field has no source event in `slice.json`, do not invent one. One read model per use case —
+never reuse a model across slices.
+
+## Step 2 — Write the slice `.cs` file
+
+`<Module>/<Feature>/<Slice>/<Slice>.cs` — namespace `<Root>.<Module>.<Feature>.<Slice>` (mirror the folders; drop any `.Features.`).
+
+### Read model + static query methods
+```csharp
+[ReadModel]
+public record AuthorListItem(AuthorId Id, AuthorName Name, int BookCount)
+{
+    public static async Task<IEnumerable<AuthorListItem>> AllAuthors(
+        IMongoCollection<AuthorListItem> collection)
+        => await collection.Find(_ => true).ToListAsync();
+
+    public static async Task<AuthorListItem?> GetAuthor(
+        AuthorId id, IMongoCollection<AuthorListItem> collection)
+        => await collection.Find(a => a.Id == id).FirstOrDefaultAsync();
+
+    // Real-time push — return ISubject<T> directly (never Task<ISubject<T>>)
+    public static ISubject<IEnumerable<AuthorListItem>> ObserveAllAuthors(
+        IMongoCollection<AuthorListItem> collection)
+        => collection.Observe();
+}
+```
+- `[ReadModel]` required. Query methods are **`public static`** on the record; the method name becomes
+  the TS query proxy class name. No controller, no `IReadModels`.
+- Favor reactive (`ISubject<T>`) queries when the slice wants live updates.
+
+### Choose projection vs reducer
+- **Projection** — shaped read models, field mapping, joins, children (most read slices).
+- **Reducer** — running aggregates (balances, counts, sums) where state accumulates across events.
+
+### Projection (declarative; AutoMap on by default)
+```csharp
+public class AuthorListItemProjection : IProjectionFor<AuthorListItem>
+{
+    public void Define(IProjectionBuilderFor<AuthorListItem> builder) => builder
+        .From<AuthorRegistered>(from => from.Set(m => m.Name).To(e => e.Name))
+        .From<BookAdded>(from => from.Add(m => m.BookCount).With(_ => 1));
+}
+```
+Or model-bound shorthand for simple cases:
+```csharp
+[ReadModel]
+public record AuthorInfo([Key] Guid Id, [FromEvent<AuthorRegistered>] string Name);
+```
+
+Projections/reducers are discovered automatically — no registration. See
+[references/patterns.md](references/patterns.md) for joins, children, composite keys, and reducers.
+
+## Step 3 — Build
+
+`dotnet build` from the project root — zero warnings / errors. This generates the query proxy the
+frontend imports.
+
+## Step 4 — Specs
+
+Write specs proving the projection/reducer produces the expected read model from a sequence of events —
+one spec per scenario in `slice.json`. Run `dotnet test --filter "FullyQualifiedName~<SliceName>"`.
+See [references/patterns.md](references/patterns.md).
+
+## Step 5 — Frontend
+
+Add `<Module>/<Feature>/<Slice>/<Component>.tsx` importing the co-located generated query proxy from
+`./` (`MyQuery.use()` snapshot, `MyQuery.useWithPaging(pageSize)` for paging, observable proxy for live
+data; or `DataTableForObservableQuery` for a table). Add a barrel `index.ts`. Register it in the
+feature's composition page; add routing in `App.tsx` if it's a new page.
+
+## Final verification — does the implementation match `slice.json`?
+
+- [ ] Every read-model field → a record property fed by a projection/reducer mapping.
+- [ ] Every source event used exists; projections map from **events**, never read models.
+- [ ] Every query in the slice is exposed as a static method; observable where the slice wants live data.
+- [ ] Every scenario → an executable spec.
+- [ ] `dotnet build` clean; specs pass.
+
+## References
+- [references/patterns.md](references/patterns.md) — full projection/reducer/query/spec code + React.
+- [../_shared/cratis-conventions.md](../_shared/cratis-conventions.md) — the Cratis conventions.

package/stacks/cratis-csharp/templates/.claude/skills/build-state-view/references/patterns.md

@@ -0,0 +1,166 @@
+# Read Slice Patterns — Cratis Arc + Chronicle
+
+Complete code for state-view (read) slices. All artifacts go in a single
+`<Module>/<Feature>/<Slice>/<Slice>.cs` (the shipped starter uses `SomeModule/SomeFeature/...` — match
+whatever the existing slices use). The example slices use no file header (match the project); namespace
+mirrors the folders and drops any `.Features.`. Examples below use short illustrative names
+(`MyApp.Authors.Listing`); mirror your project's actual module/feature layout instead.
+
+---
+
+## 1. Read model + queries (snapshot + observable)
+
+```csharp
+// Features/Authors/Listing/Listing.cs
+namespace MyApp.Authors.Listing;
+
+using System.Reactive.Subjects;
+using Cratis.Arc.Queries.ModelBound;
+using MongoDB.Driver;
+
+[ReadModel]
+public record AuthorListItem(AuthorId Id, AuthorName Name, int BookCount)
+{
+    public static async Task<IEnumerable<AuthorListItem>> AllAuthors(
+        IMongoCollection<AuthorListItem> collection)
+        => await collection.Find(Builders<AuthorListItem>.Filter.Empty).ToListAsync();
+
+    public static async Task<AuthorListItem?> GetAuthor(
+        AuthorId id, IMongoCollection<AuthorListItem> collection)
+        => await collection.Find(a => a.Id == id).FirstOrDefaultAsync();
+
+    public static ISubject<IEnumerable<AuthorListItem>> ObserveAllAuthors(
+        IMongoCollection<AuthorListItem> collection)
+        => collection.Observe();
+
+    public static ISubject<AuthorListItem> ObserveAuthor(
+        AuthorId id, IMongoCollection<AuthorListItem> collection)
+        => collection.Observe(a => a.Id == id);
+}
+```
+
+Rules: `[ReadModel]` required; methods `public static`; observable methods return `ISubject<T>`
+directly (never `Task<ISubject<T>>`); `ConceptAs<T>` for identity fields; one read model per use case.
+
+---
+
+## 2A. Projection (declarative mapping)
+
+```csharp
+public class AuthorListItemProjection : IProjectionFor<AuthorListItem>
+{
+    public void Define(IProjectionBuilderFor<AuthorListItem> builder) => builder
+        .From<AuthorRegistered>(from => from
+            .Set(m => m.Name).To(e => e.Name)
+            .Set(m => m.BookCount).WithValue(0))
+        .From<BookAdded>(from => from
+            .Add(m => m.BookCount).With(_ => 1))
+        .From<BookRemoved>(from => from
+            .Subtract(m => m.BookCount).With(_ => 1));
+}
+```
+
+- Keyed by **event source id** by default (the id passed to `IEventLog.Append`).
+- AutoMap is on — `.From<E>()` directly; matching property names map automatically.
+- Builder verbs: `Set(...).To(...)` / `.WithValue(...)`, `Add(...).With(...)`, `Subtract(...).With(...)`,
+  `.Join<T>()`, `.Children(...)`. Projections **join events, never read models**.
+
+### Model-bound shorthand (simple cases)
+```csharp
+[ReadModel]
+public record AuthorInfo(
+    [Key] Guid Id,
+    [FromEvent<AuthorRegistered>] string Name,
+    [SetFrom<AuthorRegistered>(nameof(AuthorRegistered.Country))] string Country);
+```
+
+---
+
+## 2B. Reducer (running aggregate)
+
+```csharp
+public class AccountBalanceReducer : IReducerFor<AccountBalance>
+{
+    public AccountBalance Opened(DebitAccountOpened @event, AccountBalance? current, EventContext context)
+        => new(0m, context.Occurred);
+
+    public AccountBalance Deposited(FundsDeposited @event, AccountBalance? current, EventContext context)
+        => (current ?? new(0m, context.Occurred)) with { Balance = (current?.Balance ?? 0m) + @event.Amount };
+
+    public AccountBalance Withdrawn(FundsWithdrawn @event, AccountBalance? current, EventContext context)
+        => (current ?? new(0m, context.Occurred)) with { Balance = (current?.Balance ?? 0m) - @event.Amount };
+}
+
+public record AccountBalance(decimal Balance, DateTimeOffset LastUpdated);
+```
+
+Return the complete new state; never mutate `current` (`null` on the first event). Add
+`[FilterEventsByTag]` / `[EventSourceType]` / `[EventStreamType]` when filtering by metadata.
+
+---
+
+## 3. Spec — projection result from a sequence of events
+
+```csharp
+namespace MyApp.Authors.Listing.for_AuthorListItem.when_an_author_registered_and_added_two_books;
+
+// Use the project's projection-spec harness (e.g. a ProjectionSpecificationContext / Given<context>).
+// The shape: append events, observe the resulting read model, assert fields.
+
+public class and_projecting : Specification
+{
+    AuthorListItem _result;
+
+    void Establish() { /* append AuthorRegistered, BookAdded, BookAdded to the test event store */ }
+    void Because()   { /* run the projection / read the resulting model */ }
+
+    [Fact] void should_have_the_name()      => _result.Name.Value.ShouldEqual("John");
+    [Fact] void should_count_two_books()     => _result.BookCount.ShouldEqual(2);
+}
+```
+
+Match the project's existing projection-spec harness — discover it from an existing read slice's specs.
+
+---
+
+## 4. React — render the query proxy
+
+The query proxy (`AllAuthors.ts`) is generated **next to** `Listing.cs` — import it from the same
+folder. The simplest list UI uses the Cratis `DataTableForObservableQuery` component (see the shipped
+example slice's `ListingDataTable.tsx`):
+
+```tsx
+// Authors/Listing/ListingDataTable.tsx
+import { DataTableForObservableQuery } from '@cratis/components/DataTables';
+import { Column } from 'primereact/column';
+import { AllAuthors } from './AllAuthors';   // co-located generated proxy
+
+export const ListingDataTable = () => (
+    <DataTableForObservableQuery query={AllAuthors} dataKey='id' emptyMessage='No authors yet.'>
+        <Column field='name' header='Name' />
+        <Column field='bookCount' header='Books' />
+    </DataTableForObservableQuery>
+);
+```
+
+Hook form (manual rendering):
+
+```tsx
+const [authors] = AllAuthors.use();              // snapshot or observable, depending on the proxy
+const [result, , setPage] = AllAuthors.useWithPaging(10);   // paging
+// result.data, result.paging.totalItems, result.paging.page
+```
+
+Observable queries generate an `ObservableQueryFor` proxy (from `collection.Observe()`); snapshot
+queries generate `QueryFor`. PrimeReact CSS variables / Tailwind for styling; no `any`; full
+descriptive names. Add a barrel `index.ts` for the slice.
+
+---
+
+## Checklist
+
+- One `.cs` file, namespace without `.Features.` (no file header unless the project uses one).
+- `[ReadModel]` record; `public static` query methods; observable returns `ISubject<T>` directly.
+- Projection (mapping) or reducer (aggregate) — discovered automatically, no registration.
+- Projections map from events only; one read model per use case.
+- `ConceptAs<T>` for identity fields; one spec per scenario; `dotnet build` clean; specs pass.

package/stacks/cratis-csharp/templates/.claude/skills/connect/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: connect
+description: Resolve eventmodelers connection config (token, boardId, baseUrl) from inline params or .eventmodelers/config.json — ask the user for missing values, persist them, and add the file to .gitignore. All other skills invoke this first.
+---
+
+# Connect — Resolve Eventmodelers Config
+
+**Every other skill invokes this skill first** before making any API calls. Do not proceed past this skill until all four values (`TOKEN`, `BOARD_ID`, `ORG_ID`, `BASE_URL`) are resolved.
+
+---
+
+## What this skill produces
+
+After running, the following variables are available for the rest of the session:
+
+| Variable | Header sent to API | Description |
+|----------|--------------------|-------------|
+| `TOKEN` | `x-token` | API token UUID |
+| `BOARD_ID` | `x-board-id` | Target board UUID |
+| `ORG_ID` | — | Organization UUID (used in all board-scoped URLs) |
+| `BASE_URL` | — | Base URL, e.g. `http://localhost:3000` |
+
+Every API call in every skill must include these headers:
+```
+x-token: <TOKEN>
+x-board-id: <BOARD_ID>
+x-user-id: <skill-name>   ← set by each skill individually
+```
+
+All board-scoped URLs follow the pattern: `<BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/...`
+
+---
+
+## Step 0 — Check for inline parameters
+
+Before reading the config file, scan the prompt/arguments that invoked this skill for inline overrides. Supported formats:
+
+| Pattern | Example |
+|---------|---------|
+| `board=<uuid>` | `board=05cda19d-d5b8-4b51-ae88-c72f2611548a` |
+| `token=<uuid>` | `token=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
+| `org=<uuid>` | `org=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
+| `baseUrl=<url>` | `baseUrl=http://localhost:3000` |
+
+If an inline `board=<uuid>` is found, use it as `BOARD_ID` — **it takes priority over the config file**. Same for `token`, `org`, and `baseUrl`. Record which values came from inline params so they are not overwritten in Step 3.
+
+---
+
+## Step 1 — Read config file
+
+Check whether `.eventmodelers/config.json` exists in the current working directory:
+
+```bash
+cat .eventmodelers/config.json 2>/dev/null
+```
+
+If the file exists and is valid JSON, extract any values **not already set by Step 0**:
+- `token` → `TOKEN`
+- `boardId` → `BOARD_ID`
+- `organizationId` → `ORG_ID`
+- `baseUrl` → `BASE_URL` (default: `https://api.eventmodelers.ai` if missing)
+
+Resolution priority: **inline param > config file > ask user**
+
+If all four are present (from any source), skip to **Step 4 — Verify**.
+
+---
+
+## Step 2 — Ask for missing values
+
+If after Steps 0 and 1 any required field is still missing, **ask the user one question first**:
+
+> "Do you have a config from the eventmodelers accounts page? (yes / no)"
+
+**If the user answers yes:**
+Stop asking questions. Show this hint and wait for them to paste:
+
+> "Great — please paste your config from https://app.eventmodelers.ai/account here."
+
+When they paste a JSON object, parse it immediately — accept both `orgId` and `organizationId` as the organization field — apply all values, and proceed directly to Step 3.
+
+**If the user answers no** (or pastes only a partial config), ask for each still-missing field one at a time, in this order: `token`, then `boardId`, then `orgId`. Wait for the answer before asking the next.
+
+| Field | What to ask |
+|-------|-------------|
+| `token` | "Please provide your eventmodelers API token (a UUID from your workspace settings)." |
+| `boardId` | "Please provide the board ID you want to work with (the UUID from the board URL)." |
+| `orgId` | "Please provide your organization ID (the UUID from your organization settings)." |
+| `baseUrl` | Do **not** ask — default to `https://api.eventmodelers.ai` silently. |
+
+Where to find the token: users generate API tokens in their workspace settings at the eventmodelers platform. The token is shown only once at creation time. It is a UUID and must belong to the same organization as the board.
+
+---
+
+## Step 3 — Persist config
+
+Once all values are collected, write the config file. When writing, merge with any existing config — do **not** overwrite fields that were provided as inline params with values from a previous config (the inline param is the user's explicit intent for this session, but the persisted value should reflect the most recently user-supplied value):
+
+```bash
+mkdir -p .eventmodelers
+cat > .eventmodelers/config.json << 'EOF'
+{
+  "token": "<TOKEN>",
+  "boardId": "<BOARD_ID>",
+  "orgId": "<ORG_ID>",
+  "baseUrl": "<BASE_URL>"
+}
+EOF
+```
+
+Then ensure `.eventmodelers/config.json` is in `.gitignore`. Check whether it is already present:
+
+```bash
+grep -q ".eventmodelers/config.json" .gitignore 2>/dev/null || echo "MISSING"
+```
+
+If `MISSING`, append it:
+
+```bash
+echo ".eventmodelers/config.json" >> .gitignore
+```
+
+Tell the user: `"Config saved to .eventmodelers/config.json and added to .gitignore."`
+
+---
+
+## Step 4 — Verify
+
+Confirm the token and board are valid with a lightweight call:
+
+```bash
+curl -s -o /dev/null -w "%{http_code}" \
+  -H "x-token: <TOKEN>" \
+  -H "x-board-id: <BOARD_ID>" \
+  -H "x-user-id: connect-skill" \
+  "<BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes?type=CHAPTER"
+```
+
+| Response | Action |
+|----------|--------|
+| `200` | Config is valid. Print one line: `"Connected — board <BOARD_ID>"` and return. |
+| `401` | Token is invalid or missing. Tell the user and re-run from Step 2, clearing `token`. |
+| `403` | Token organization does not match board. Tell the user to check that the token was issued for the correct workspace. Re-run from Step 2 for both fields. |
+| `404` | Board not found. Tell the user and re-run from Step 2, clearing `boardId`. |
+| Any other | Print the status code and raw response. Ask the user how to proceed. |
+
+---
+
+## Config file format
+
+`.eventmodelers/config.json`:
+```json
+{
+  "token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+  "boardId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+  "orgId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+  "baseUrl": "http://localhost:3000"
+}
+```
+
+The `token` field is a secret. It is never logged or shown after initial confirmation.
+
+---
+
+## Security notes
+
+- The config file is workspace-local and gitignored — never commit it.
+- The token grants write access to all boards in its organization — treat it like a password.
+- If a skill receives a `401` or `403` mid-session, re-invoke this skill to refresh the config before retrying.