ecoportal-api-graphql 1.3.5 → 1.3.9

data/.ai-assistance/code/workflow-space.md

@@ -0,0 +1,353 @@
+# Workflow Space — Code Spec
+
+*Read this before working on `PagesWorkflow`, `Model::PagesWorkflow`, or `Input::WorkflowCommand`.*
+
+---
+
+## Overview
+
+The Workflow Space covers two distinct subsystems that share the word "workflow":
+
+1. **The read model** (`PagesWorkflow`) — queried as `page.workflow` — describes the
+   automation configuration attached to a template or page (stages, fields, callbacks).
+2. **The command bus** (`executeWorkflowCommands`) — a single mutation that accepts an
+   array of `WorkflowCommandInput` objects to structurally modify a template or page
+   (add/rename stages, add fields, configure field options, set up callbacks, etc.).
+
+These are deeply related but separate code areas.
+
+---
+
+## SCHEMA_VERSION
+
+All files in this area carry:
+
+```ruby
+SCHEMA_VERSION = '20260605'.freeze
+```
+
+This constant tracks the introspection snapshot used to derive the type list:
+`20260605T101224_live_ep_graphql_schema.graphql.json`.
+
+**When to update:** Re-run schema introspection and update this constant (across all
+affected files) when engineering reports schema changes to the Workflow Builder types.
+Use `grep -r SCHEMA_VERSION lib/` to find all files that need updating.
+Do not update the constant speculatively — only after verified re-introspection.
+
+---
+
+## W1 — Read Model: PagesWorkflow
+
+### What it is
+
+`PagesWorkflow` is the workflow configuration embedded on every page (and template).
+It is available at `page.workflow` when the `PagesWorkflowFields` fragment is included
+in the query. It is NOT automatically included in `CommonPageUnion` — callers must
+request it explicitly.
+
+### Type hierarchy
+
+```
+PagesWorkflow
+  autoPageCreationEnabled: Boolean!
+  fields:  [RegisterField!]!       — field registry (key/name/type/total)
+  stages:  [Stage!]!               — stage list (id, name, ordering, state, active, started)
+  commands: PagesWorkflowCommandInterfaceConnection!  — paginated command log (deferred F.2)
+```
+
+**CallbackType** — attached to stages (requires `PagesWorkflowCallbackFields` fragment
+on Stage — see gap F.3):
+
+```
+PagesWorkflowCallbackType
+  id, triggerCondition: CallbackTriggerConditionEnum!
+  triggers:   [PagesWorkflowTriggerInterface!]!
+  operations: [PagesWorkflowOperationInterface!]!
+```
+
+**OperationInterface** — dispatches to three concrete types via `__typename`:
+
+```
+PagesWorkflowOperationInterface
+  id, timeDelayPassed: Boolean!, timeDelayConfig, delayedExecuteAt
+
+  PagesWorkflowOperationsAssignTo    — task assignment automation
+    targetTaskType, lastFulfilled, strategies, escalationLevels
+
+  PagesWorkflowOperationsCreatePage  — auto-create a page on trigger
+    templateId, crossReferenceFieldId
+
+  PagesWorkflowOperationsSendNotification  — notification dispatch
+    recurring, recurrenceActive, emailConfig, inSystemConfig, recipientConfig, ...
+```
+
+**TriggerInterface** — dispatches to one concrete type:
+
+```
+PagesWorkflowTriggerInterface
+  id
+
+  PagesWorkflowTriggersConditionalLogic  — field-value conditions
+    filters: [StoredEsFilter!]!
+```
+
+**CommandInterface** — the paginated command log (audit trail), dispatches to three:
+
+```
+PagesWorkflowCommandInterface
+  id, commandAction, createdAt, patchVer, ownerId, stageId, stageName, taskId
+
+  PagesWorkflowCommandChange        — structured diff changes
+    changes: [Change!]!
+  PagesWorkflowCommandChangeMessage — free-text change messages
+    changeMessages: [String!]!
+  PagesWorkflowCommandEsChange      — ES filter changes
+    changes: [StoredEsFilterChange!]!
+```
+
+### Ruby implementation
+
+| Layer | Class | File |
+|---|---|---|
+| Base model | `Base::PagesWorkflow` | `lib/ecoportal/api/graphql/base/pages_workflow.rb` |
+| Read model | `Model::PagesWorkflow` | `lib/ecoportal/api/graphql/model/pages_workflow.rb` |
+| Callback | `Base::PagesWorkflow::CallbackType` | `base/pages_workflow/callback_type.rb` |
+| Operation base | `Base::PagesWorkflow::OperationInterface` | `base/pages_workflow/operation_interface.rb` |
+| AssignTo | `Base::PagesWorkflow::Operations::AssignTo` | `base/pages_workflow/operations/assign_to.rb` |
+| CreatePage | `Base::PagesWorkflow::Operations::CreatePage` | `base/pages_workflow/operations/create_page.rb` |
+| SendNotification | `Base::PagesWorkflow::Operations::SendNotification` | `base/pages_workflow/operations/send_notification.rb` |
+| Trigger base | `Base::PagesWorkflow::TriggerInterface` | `base/pages_workflow/trigger_interface.rb` |
+| ConditionalLogic | `Base::PagesWorkflow::Triggers::ConditionalLogic` | `base/pages_workflow/triggers/conditional_logic.rb` |
+| Command base | `Base::PagesWorkflow::CommandInterface` | `base/pages_workflow/command_interface.rb` |
+| CommandChange | `Base::PagesWorkflow::CommandChange` | `base/pages_workflow/command_change.rb` |
+| CommandChangeMessage | `Base::PagesWorkflow::CommandChangeMessage` | `base/pages_workflow/command_change_message.rb` |
+| CommandEsChange | `Base::PagesWorkflow::CommandEsChange` | `base/pages_workflow/command_es_change.rb` |
+
+Supporting value objects: `RegisterField`, `TimeDelayConfig`, `EscalationLevel`,
+`EmailConfig`, `InSystemConfig`, `RecipientConfig`, `UserSelection`,
+`PeopleFieldSelection`, `TaskConfigSelection`, `ActionTypeSelection`,
+`MailboxFieldSelection`.
+
+### Fragments
+
+Three fragments are defined in `lib/ecoportal/api/graphql/fragment/pages_workflow.rb`:
+
+| Fragment constant | GraphQL fragment name | Purpose |
+|---|---|---|
+| `:PagesWorkflowFields` | `PagesWorkflowFields on PagesWorkflow` | Core read model (autoPageCreationEnabled, fields, stages) |
+| `:PagesWorkflowCallbackFields` | `PagesWorkflowCallbackFields on PagesWorkflowCallbackType` | Full callback with triggers + operations (all three operation types) |
+| `:PagesWorkflowCommandFields` | `PagesWorkflowCommandFields on PagesWorkflowCommandInterface` | Command log entries |
+
+### How to access workflow on a page
+
+The `workflow` field on `BasePageInterface` is mapped but NOT included in
+`CommonPageUnion`. You must query it explicitly with the `PagesWorkflowFields` fragment:
+
+```ruby
+page = graphql.currentOrganization.page(id: page_id) do
+  spread :PagesWorkflowFields   # adds workflow { autoPageCreationEnabled fields { ... } stages { ... } }
+  id
+  name
+  patchVer
+end
+
+page.workflow.auto_page_creation_enabled  # => Boolean
+page.workflow.stages                       # => Array of raw Stage hashes (id, name, ordering, state)
+page.workflow.fields                       # => Array of RegisterField instances
+```
+
+**Note:** `page.workflow.stages` returns raw stage data, not `Base::Page::Phased::Stage`
+instances. For full stage access (sections, components, tasks), use the normal page query
+with `CommonPageUnion`.
+
+### How to read callbacks (via stage)
+
+Stage-level callbacks require the `PagesWorkflowCallbackFields` fragment to be spread
+on the `Stage` type. This is not yet wired into the standard stage fragment — see F.3.
+
+When available:
+
+```ruby
+stage = page.stages['Risk Assessment']
+stage.workflow_callbacks.each do |cb|
+  puts cb.trigger_condition
+  cb.operations.each { |op| puts op.class.name }
+end
+```
+
+---
+
+## W2-W5 — Write Model: Command Bus
+
+### What it is
+
+`executeWorkflowCommands` is the single mutation used for all structural changes to
+a template or page workflow. Rather than individual mutations per action, it accepts
+an ordered array of `WorkflowCommandInput` objects — each is a one-key hash dispatching
+to a typed sub-input.
+
+### Mutation signature
+
+```graphql
+mutation ExecuteWorkflowCommands($input: ExecuteWorkflowCommandsInput!) {
+  executeWorkflowCommands(input: $input) {
+    patchVer
+    item { autoPageCreationEnabled fields { ... } stages { ... } }
+    errors { details fullMessages }
+  }
+}
+```
+
+`ExecuteWorkflowCommandsInput`:
+- `id: ID!` — the page or template ID
+- `patchVer: Int!` — optimistic concurrency lock (required, not optional)
+- `commands: [WorkflowCommandInput!]!` — the command array
+
+### Ruby classes
+
+| Class | File | Purpose |
+|---|---|---|
+| `Mutation::Page::ExecuteWorkflowCommands` | `mutation/page/execute_workflow_commands.rb` | Executes the mutation |
+| `Payload::ExecuteWorkflowCommands` | `payload/execute_workflow_commands.rb` | Wraps response: `patchVer`, `item` (PagesWorkflow), `success?`, `error?`, `body` |
+| `Input::WorkflowCommand` | `input/workflow_command.rb` | Dispatcher: `COMMAND_MAP` + `.build(key, **kwargs)` |
+| `Input::WorkflowCommand::*` | `input/workflow_command/*.rb` | ~83 sub-input modules (one per command key) |
+| `Connection::PagesWorkflowCommand` | `connection/pages_workflow_command.rb` | Paginated command log connection |
+
+### Input::WorkflowCommand — dispatcher
+
+`Input::WorkflowCommand` is a pure factory — no instances, only class methods:
+
+```ruby
+# Build a single command hash
+cmd = Input::WorkflowCommand.build(:editPage, name: 'New Title')
+# => { editPage: { name: 'New Title' } }
+
+# Build multiple commands
+cmds = [
+  Input::WorkflowCommand.build(:editPage, name: 'New Title', icon: 'star'),
+  Input::WorkflowCommand.build(:editStage, stageId: 's1', name: 'Phase 1'),
+]
+
+# Execute all commands in one mutation call
+payload = Mutation::Page::ExecuteWorkflowCommands.new(client).query(
+  id:        page_id,
+  patch_ver: page.patchVer,
+  commands:  cmds
+)
+
+raise "Workflow command failed: #{payload.body}" unless payload.success?
+new_patch_ver = payload.patchVer
+```
+
+**Important:** `patchVer` is required and non-optional on `ExecuteWorkflowCommandsInput`.
+Always fetch the current page before calling this mutation.
+
+### `Builder::Page` integration
+
+The low-level mutation class `Mutation::Page::ExecuteWorkflowCommands` exists and is
+functional. `Builder::Page#execute_workflow_commands` is a **deferred item** (see F.4)
+— the convenience wrapper on `Builder::Page` is not yet present.
+
+Until it is wired, call the mutation directly:
+
+```ruby
+payload = Mutation::Page::ExecuteWorkflowCommands.new(client).query(
+  id:        page_id,
+  patch_ver: page.patchVer,
+  commands:  cmds
+)
+```
+
+### Template mutations
+
+Template structural mutations use the same `executeWorkflowCommands` mutation and the
+same `WorkflowCommandInput` command bus. Engineering has confirmed the back-end is ready.
+
+Template mutations are guarded by an `allow_template_mutations` flag (planned for
+`Builder::Page` — see F.4). Until that guard is implemented, take care when targeting
+template IDs — structural changes to templates affect all pages created from them.
+
+### Payload
+
+`Payload::ExecuteWorkflowCommands` provides:
+
+```ruby
+payload.success?    # => Boolean — true if no errors
+payload.error?      # => Boolean — true if errors array is non-empty
+payload.body        # => raw errors array (for logging)
+payload.patchVer    # => Integer — updated patchVer after commands applied
+payload.item        # => Model::PagesWorkflow — read back the updated workflow state
+```
+
+---
+
+## Concerns::Deprecation — warn_once Pattern
+
+`Concerns::Deprecation` provides a process-level warning deduplicator used in this
+and other areas of the gem:
+
+```ruby
+Concerns::Deprecation.warn_once(:some_key, 'This method is deprecated — use X instead.')
+# Prints once to stderr; subsequent calls with the same key are silenced.
+```
+
+The `SCHEMA_VERSION` constant on `Concerns::Deprecation` tracks the same introspection
+snapshot as the workflow command classes.
+
+---
+
+## Gap Table — PageInput vs WorkflowCommand
+
+These fields are NOT settable via `UpdatePageInput → page: PageInput` but ARE settable
+via `WorkflowCommand.build(:editPage, ...)`:
+
+| Goal | NOT in PageInput | Use instead |
+|------|------------------|-------------|
+| Change page icon | | `editPage: { icon: 'star' }` |
+| Change theme | | `editPage: { themeId: 'THEME_ID' }` |
+| Enable/disable counter | | `editPage: { counterEnabled: true, counterPrefix: 'REC-' }` |
+| Set counter value | | `editPage: { counter: 42 }` |
+| Show/hide creator field | | `editPage: { showCreator: true }` |
+| Toggle comments | | `editPage: { disableComments: false }` |
+| Enable dashboard import | | `editPage: { enableDashboardImport: true }` |
+| Mobile layout settings | | `editPage: { mobileEnabled: true, useSectionsOnMobile: true }` |
+| Restricted stage display | | `editPage: { showStrategyForRestrictedStages: true }` |
+| Manage folder membership | | `editPage: { addFolders: ['F1'], removeFolders: ['F2'] }` |
+
+---
+
+## Gap Table — DataFieldInput vs WorkflowCommand
+
+These field configuration properties are NOT settable via `DataFieldInput` (the per-field
+value update in `updatePage`) but ARE settable via
+`WorkflowCommand.build(:editFieldConfiguration, ...)`:
+
+| Goal | NOT in DataFieldInput | Use instead |
+|------|----------------------|-------------|
+| Rename a field label | | `editFieldConfiguration: { dataFieldId: 'F', label: 'New Name' }` |
+| Set field tooltip/description | | `editFieldConfiguration: { dataFieldId: 'F', tooltip: '...', description: '...' }` |
+| Hide field in view | | `editFieldConfiguration: { dataFieldId: 'F', hideView: true }` |
+| Configure people field type | | `editFieldConfiguration: { dataFieldId: 'F', byType: { people: { singular: true, personSchemaId: 'S' } } }` |
+| Configure select options | | `addSelectFieldOption`, `editSelectFieldOption`, `removeSelectFieldOption` commands |
+| Configure gauge stops | | `addGaugeFieldStop`, `editGaugeFieldStop`, `removeGaugeFieldStop` commands |
+| Configure cross-reference | | `editFieldConfiguration: { dataFieldId: 'F', byType: { crossReference: { registerId: 'R', singleSelectMode: true } } }` |
+| Configure date (show time) | | `editFieldConfiguration: { dataFieldId: 'F', byType: { date: { showTime: true } } }` |
+| Configure image gallery layout | | `editFieldConfiguration: { dataFieldId: 'F', byType: { imageGallery: { layout: 'GRID' } } }` |
+| Set linked field config | | `addLinkedFieldConfig: { dataFieldId: 'F', sourceFieldKey: 'key', crossReferenceId: 'CR' }` |
+
+---
+
+## Related Files
+
+```
+lib/ecoportal/api/graphql/base/pages_workflow.rb          ← Base model root
+lib/ecoportal/api/graphql/model/pages_workflow.rb         ← Model with class_resolver wiring
+lib/ecoportal/api/graphql/input/workflow_command.rb       ← Dispatcher + COMMAND_MAP
+lib/ecoportal/api/graphql/input/workflow_command/         ← ~83 sub-input modules
+lib/ecoportal/api/graphql/mutation/page/execute_workflow_commands.rb
+lib/ecoportal/api/graphql/payload/execute_workflow_commands.rb
+lib/ecoportal/api/graphql/fragment/pages_workflow.rb      ← 3 fragments
+lib/ecoportal/api/graphql/concerns/deprecation.rb         ← warn_once
+.ai-assistance/code/workflow-command-guide.md             ← porting guide with full command table
+.ai-assistance/projects/workflow-space/TODO.md            ← W1-W5 phase tracking
+```

data/.ai-assistance/conventions/CLAUDE.md

@@ -0,0 +1,30 @@
+# Conventions — AI Instruction Files
+
+## Rule: every subfolder that contains AI-readable instructions must have its own CLAUDE.md
+
+The root `.ai-assistance/CLAUDE.md` is the entry point only. It does not duplicate rules — it
+references subfolders. Each subfolder owns its own rules.
+
+## Subfolder registry
+
+| Folder | CLAUDE.md purpose |
+|--------|-------------------|
+| `.ai-assistance/` | Startup sequence, env detection, delegation rule |
+| `.ai-assistance/bridge/` | Bridge protocol: file format, task lifecycle, who processes what |
+| `.ai-assistance/capabilities/` | How to read/update capability and connector files |
+| `.ai-assistance/conventions/` | This file — rules for instruction file structure |
+| `.ai-assistance/scripts/` | Index of scripts, when to call each, expected I/O |
+
+## Rules for adding new subfolders
+
+1. Create the folder
+2. Add a `CLAUDE.md` describing its purpose and any rules specific to it
+3. Register it in this file (the table above)
+4. Reference it from the root `.ai-assistance/CLAUDE.md` if startup behaviour is needed
+
+## Rules for CLAUDE.md files
+
+- Be explicit, not implicit — assume the reading agent has no prior context
+- No cross-referencing rules from memory — link to the file
+- Keep each CLAUDE.md focused on its folder only
+- Date-stamp any assumptions so the capabilities-check agent can identify stale content

data/.ai-assistance/conventions/code-working-tree-protocol.md

@@ -0,0 +1,199 @@
+# Code Working Tree Protocol
+
+When Claude Code needs to make changes to files **outside** `bridge/inbox/`, it must
+follow this protocol. This prevents Code's changes from mixing with in-progress CoWork
+edits and ensures a clean, traceable commit history.
+
+---
+
+## When this applies
+
+Any time Code intends to modify files in the working tree that are not bridge task files
+(i.e., not `.ai-assistance/bridge/inbox/` or `.ai-assistance/bridge/outbox/`).
+
+This includes: editing source files, updating documentation, changing scripts,
+modifying capabilities files, etc.
+
+---
+
+## Protocol
+
+### 0. Check for a lock
+
+```bash
+cat .ai-assistance/bridge/LOCK 2>/dev/null || echo "NO_LOCK"
+```
+
+- **No lock:** proceed to step 1
+- **Lock exists, EXPIRES is in the future:** stop. Tell the user:
+  > "Working tree is locked by [AGENT] ([USER]) since [ACQUIRED], working on: [INTENT].
+  > Expires at [EXPIRES]. Please wait or check if the other session is still active."
+- **Lock exists, EXPIRES is in the past:** stale lock — safe to overwrite, proceed to step 1
+
+---
+
+### 1. Acquire the lock
+
+Write `.ai-assistance/bridge/LOCK` with full watermark:
+
+```
+AGENT: code
+USER: [git config user.name, lowercased]
+ACQUIRED: [ISO 8601 now]
+EXPIRES: [ISO 8601 now + 30 minutes]
+INTENT: [one sentence — what you are about to change and why]
+FILES: [comma-separated list of files you plan to modify]
+```
+
+Example:
+```
+AGENT: code
+USER: oscar
+ACQUIRED: 2026-06-04T10:00:00Z
+EXPIRES: 2026-06-04T10:30:00Z
+INTENT: Update gitlab-mcp.md with new PAT scopes and rotation info
+FILES: .ai-assistance/integrations/gitlab-mcp.md
+```
+
+---
+
+### 2. Check for unstaged changes that overlap with your planned files
+
+```bash
+git status --short
+```
+
+If the working tree is clean, skip to step 3.
+
+If there are unstaged/staged changes, compare them against the files listed in your LOCK:
+
+```bash
+git diff --name-only HEAD
+git diff --cached --name-only
+```
+
+- **No overlap with your FILES:** proceed — the changes are unrelated and won't pollute history
+- **Overlap with one or more of your FILES:** commit the unstaged changes first.
+  Derive the commit message by running `git diff HEAD` on the overlapping files and
+  writing a short imperative summary of what actually changed — do not use a generic
+  message. Format: `wip: <what changed, e.g. "rename .claude to .ai-assistance across scripts">`
+
+```bash
+git add -A
+git commit -m "wip: <derived from actual diff>"
+```
+
+This keeps Code's subsequent commit clean and ensures both sets of changes build
+on the correct base. On a feature branch, `wip:` commits are fine — squash before MR.
+
+---
+
+### 3. Apply your changes
+
+Make the intended file edits. Stay within the scope declared in INTENT and FILES
+when you acquired the lock. If scope expands, update the LOCK file before proceeding.
+
+---
+
+### 4. Commit your changes
+
+```bash
+git add -A
+git commit -m "[descriptive message — what Code changed and why]"
+```
+
+Commit message should be specific enough that a teammate can understand the change
+without reading the diff. Example:
+```
+docs: update gitlab-mcp.md scopes and rotation info for new PAT (April 2027 expiry)
+```
+
+**Commit authorship — developer only by default:**
+
+Commits are authored by the developer alone (git's `user.name` / `user.email` config).
+Do NOT add `Co-Authored-By: Claude ...` to commit messages unless the developer
+explicitly requests it.
+
+Rationale: the commit history is the developer's professional record. Co-authorship is
+opt-in, not opt-out. If the developer wants to attribute AI involvement, they can add
+it themselves or ask Claude to include it for a specific commit.
+
+Before adding any co-authorship attribution, ask:
+> "Would you like to add AI co-authorship to this commit, or keep it as your commit alone?"
+
+Default answer if not asked: **developer only**.
+
+---
+
+### 5. Release the lock
+
+```bash
+rm .ai-assistance/bridge/LOCK
+```
+
+---
+
+## External-fork branch protocol
+
+When the task involves a **fork of an external gem** (not team-managed), an extra check
+applies **before step 1** above:
+
+1. Look up the gem in `.ai-assistance/code/dependencies.md`.
+2. Read the `Git workflow` row. If it says **"ALWAYS use a feature branch"** or
+   **"upstream-contribution only"**, you MUST:
+   - Create a dedicated feature/fix branch (e.g. `feature/<description>`) — NEVER commit to `master`.
+   - If the branch name was not specified by the developer, derive one from the work and
+     **tell the developer what branch you created** before committing anything.
+3. If the `Git workflow` row is absent or ambiguous, **ask the developer** which branch
+   to use before proceeding. Do not guess.
+
+This rule applies even inside background agents — the branch strategy must be resolved
+in the prompt given to the agent, not inferred at runtime.
+
+**Why:** Commits on `master` of an external fork pollute the base from which upstream
+PRs are diffed. A feature branch produces a clean, reviewable diff against upstream's
+`master`.
+
+---
+
+## Quick reference
+
+```bash
+# 0. Check lock
+cat .ai-assistance/bridge/LOCK 2>/dev/null || echo "NO_LOCK"
+
+# 1. Acquire lock
+cat > .ai-assistance/bridge/LOCK << EOF
+AGENT: code
+USER: oscar
+ACQUIRED: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+EXPIRES: $(date -u -d "+30 minutes" +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date -u -v+30M +"%Y-%m-%dT%H:%M:%SZ")
+INTENT: <what you are changing>
+FILES: <files>
+EOF
+
+# 2. Check for overlapping unstaged changes
+git diff --name-only HEAD && git diff --cached --name-only
+# If any of those files overlap with your planned FILES → commit them first:
+git add -A && git commit -m "wip: <description of CoWork's in-progress work>"
+# If no overlap → skip, proceed directly
+
+# 3. Apply changes
+# ... make edits ...
+
+# 4. Commit your changes
+git add -A && git commit -m "<descriptive message>"
+
+# 5. Release lock
+rm .ai-assistance/bridge/LOCK
+```
+
+---
+
+## Notes
+
+- If Code crashes mid-protocol, the LOCK will expire naturally (30 min timeout)
+- The `wip:` commit prefix signals to teammates that this was an auto-committed
+  in-progress state — safe to squash or amend later
+- This protocol does not apply to bridge task processing (reading inbox, writing outbox)
+  — those are read/write of bridge files only and don't touch the working tree

data/.ai-assistance/conventions/gitignore-rules.md

@@ -0,0 +1,42 @@
+# .gitignore Rules for .ai-assistance/
+
+## What stays local (never commit)
+
+| Pattern | Reason |
+|---------|--------|
+| `bridge/inbox/*.draft.md` | Work-in-progress tasks not ready to share |
+| `bridge/inbox/*.local.md` | Tasks intended only for local Code session |
+| `bridge/LOCK` | Working tree lock — local only, never committed |
+| `capabilities/.env` | Any credential or token file |
+| `scripts/*.env` | Script-level secrets |
+| `scripts/node_modules/` | Dependencies, not source |
+
+## What gets committed
+
+Everything else under `.ai-assistance/` is committed. This includes:
+
+- All `CLAUDE.md` files
+- `bridge/inbox/[username]-[uuid]-[slug].md` — pushed tasks are intentionally shared
+- `bridge/outbox/` — completed results are shared
+- `bridge/archive/` — history is useful, keep it
+- `capabilities/*.md` — shared knowledge
+- `conventions/*.md` — shared rules
+- `scripts/*.sh`, `scripts/*.ts` — shared tooling
+
+## Why archive/ is committed
+
+Completed task pairs in `archive/` are the audit trail of AI-assisted work.
+They answer: what did we ask, what did we get back, when. Keep them.
+Prune manually if the folder grows unwieldy.
+
+## Gitignore entries (copy these to your project root .gitignore)
+
+```
+# AI assistance — local-only files
+.ai-assistance/bridge/inbox/*.draft.md
+.ai-assistance/bridge/inbox/*.local.md
+.ai-assistance/bridge/LOCK
+.ai-assistance/capabilities/.env
+.ai-assistance/scripts/*.env
+.ai-assistance/scripts/node_modules/
+```