@use-the-fork/spindle 0.0.1 → 0.1.0

package/build/Assets/Blueprints/Catalog.js

@@ -62,14 +62,14 @@ export const blueprintCatalog = {
     skills: {
         "asd-ste100": { path: "asd-ste100/", status: "active", stacks: [] },
         "author-agent": { path: "author-agent/", status: "active", stacks: [] },
-        "author-design": { path: "author-design/", status: "active", stacks: [] },
+        "sdd-author-design": { path: "sdd-author-design/", status: "active", stacks: [] },
         "author-instruction": { path: "author-instruction/", status: "active", stacks: [] },
         "author-skill": { path: "author-skill/", status: "active", stacks: [] },
         grill: { path: "grill/", status: "active", stacks: [] },
-        "grill-design": { path: "grill-design/", status: "active", stacks: [] },
+        "sdd-grill-design": { path: "sdd-grill-design/", status: "active", stacks: [] },
         "grill-with-docs": { path: "grill-with-docs/", status: "active", stacks: [] },
         implement: { path: "implement/", status: "active", stacks: [] },
-        "implement-spec": { path: "implement-spec/", status: "active", stacks: [] },
+        "sdd-implement-spec": { path: "sdd-implement-spec/", status: "active", stacks: [] },
         "improve-codebase-architecture": {
             path: "improve-codebase-architecture/",
             status: "active",
@@ -102,9 +102,14 @@ export const blueprintCatalog = {
         "int-writing-instruction": { path: "int-writing-instruction/", status: "active", stacks: [] },
         "int-writing-skills": { path: "int-writing-skills/", status: "active", stacks: [] },
         retrospective: { path: "retrospective/", status: "active", stacks: [] },
-        "setup-project": { path: "setup-project/", status: "active", stacks: [] },
-        "to-spec": { path: "to-spec/", status: "active", stacks: [] },
-        "to-tickets": { path: "to-tickets/", status: "active", stacks: [] },
-        "update-tooling": { path: "update-tooling/", status: "active", stacks: [] },
+        "ref-php-laravel-saloon-api-integrations": {
+            path: "ref-php-laravel-saloon-api-integrations/",
+            status: "active",
+            stacks: ["php-laravel"],
+        },
+        "sdd-to-spec": { path: "sdd-to-spec/", status: "active", stacks: [] },
+        "sdd-to-tickets": { path: "sdd-to-tickets/", status: "active", stacks: [] },
+        "spindle-project-setup": { path: "spindle-project-setup/", status: "active", stacks: [] },
+        "spindle-tooling-update": { path: "spindle-tooling-update/", status: "active", stacks: [] },
     },
 };

package/build/Assets/Blueprints/skills/author-agent/SKILL.md

@@ -1,26 +1,27 @@
 ---
 name: author-agent
 description: Create or revise a workspace custom agent from requirements.
-argument-hint: "[--test] <agent idea or requirements>"
+argument-hint: "<agent idea or requirements>"
 disable-model-invocation: true
 user-invocable: true
 metadata:
   spindle:
-    version: 1.0.0
+    version: 1.0.2
 ---
 
 Create or update a project agent in `.github/agents/<agent-name>.agent.md` based on the user's requirements.
 
-## Required skills
+## Authoring flow
 
-Before drafting or editing, read:
+{{ computed.authoring_flowchart }}
+
+Before grilling, read and consider only the `int-writing-for-agents` and `asd-ste100` skills. Do not follow their workflows or load skills they reference yet.
+
+After the user confirms shared understanding, load and follow:
 
 - **REQUIRED:** `int-writing-agents`
-- **REQUIRED:** `int-writing-for-agents`
 - **REQUIRED:** `int-testing-agent-guidance`
 
-These skills define the complete authoring workflow. Every agent change requires the baseline and focused validation specified by `int-testing-agent-guidance`; `--test` does not disable or replace them.
-
-When `--test` is present, also run the expanded testing workflow in `int-testing-agent-guidance`.
+Apply the clarity rules from the `asd-ste100` skill. Include a before/after table only when the user requests one. Run the core and expanded testing workflows in `int-testing-agent-guidance` for every authoring request.
 
 Do not modify unrelated files. Report the skill changed and validation performed, including any blockers or unverified requirements.

package/build/Assets/Blueprints/skills/author-instruction/SKILL.md

@@ -1,27 +1,28 @@
 ---
 name: author-instruction
 description: Create or revise workspace-scoped Copilot instruction files from the user's requirements
-argument-hint: "[--test] <instruction requirements>"
+argument-hint: "<instruction requirements>"
 disable-model-invocation: true
 user-invocable: true
 metadata:
   spindle:
-    version: 1.0.0
+    version: 1.0.2
 ---
 
 Create or update a project instruction in `.github/instructions/**/*.instructions.md` based on the user's requirements.
 
-## Required skills
+## Authoring flow
 
-Before drafting or editing, read:
+{{ computed.authoring_flowchart }}
+
+Before grilling, read and consider only the `int-writing-for-agents` and `asd-ste100` skills. Do not follow their workflows or load skills they reference yet.
+
+After the user confirms shared understanding, load and follow:
 
 - **REQUIRED:** `int-writing-instruction`
-- **REQUIRED:** `int-writing-for-agents`
 - **REQUIRED:** `int-testing-agent-guidance`
 
-These skills define the complete authoring workflow. Every instruction change requires the baseline and focused validation specified by `int-testing-agent-guidance`; `--test` does not disable or replace them.
-
-When `--test` is present, also run the expanded testing workflow in `int-testing-agent-guidance`.
+Apply the clarity rules from the `asd-ste100` skill. Include a before/after table only when the user requests one. Run the core and expanded testing workflows in `int-testing-agent-guidance` for every authoring request.
 
 Verify any `applyTo` glob against concrete in-scope files and near misses; every intended file must match, and out-of-scope files must not.
 

package/build/Assets/Blueprints/skills/author-skill/SKILL.md

@@ -1,26 +1,27 @@
 ---
 name: author-skill
 description: Create or update a project skill from the user's requirements
-argument-hint: "[--test] <skill idea or requirements>"
+argument-hint: "<skill idea or requirements>"
 disable-model-invocation: true
 user-invocable: true
 metadata:
   spindle:
-    version: 1.0.0
+    version: 1.0.2
 ---
 
 Create or update a project skill in `.github/skills/<skill-name>/SKILL.md` based on the user's requirements.
 
-## Required skills
+## Authoring flow
 
-Before drafting or editing, read:
+{{ computed.authoring_flowchart }}
+
+Before grilling, read and consider only the `int-writing-for-agents` and `asd-ste100` skills. Do not follow their workflows or load skills they reference yet.
+
+After the user confirms shared understanding, load and follow:
 
 - **REQUIRED:** `int-writing-skills`
-- **REQUIRED:** `int-writing-for-agents`
 - **REQUIRED:** `int-testing-agent-guidance`
 
-These skills define the complete authoring workflow. Every skill change requires the baseline and focused validation specified by `int-testing-agent-guidance`; `--test` does not disable or replace them.
-
-When `--test` is present, also run the expanded testing workflow in `int-testing-agent-guidance`.
+Apply the clarity rules from the `asd-ste100` skill. Include a before/after table only when the user requests one. Run the core and expanded testing workflows in `int-testing-agent-guidance` for every authoring request.
 
 Do not modify unrelated files. Report the skill changed and validation performed, including any blockers or unverified requirements.

package/build/Assets/Blueprints/skills/grill/SKILL.md

@@ -4,7 +4,7 @@ description: "Grill the user relentlessly about a plan, decision, or idea. Use w
 user-invocable: false
 metadata:
   spindle:
-    version: 1.0.2
+    version: 1.0.3
 ---
 
 Stress-test the user's proposal until its decisions are explicit and you share an understanding. Treat dependent decisions as a **design tree**.
@@ -16,13 +16,13 @@ Stress-test the user's proposal until its decisions are explicit and you share a
 3. Apply the answer and continue the queue, revising or skipping questions whose premises changed. Newly unlocked decisions wait for the next round.
 4. When the queue is exhausted, recompute the frontier and start the next round.
 
-Label each question visibly as **Round <R>, Question <Q> of <TOTAL> - <title>**, in chat or the tool's user-visible title. Start both counters at 1; increment the question number for each question asked and reset it to 1 when the round advances. The first question announces the new round without exposing the remaining queue.
+Label each question visibly as **Round <R>, Question <Q> - <title>**, in chat or the tool's user-visible title. Start both counters at 1; increment the question number for each question asked and reset it to 1 when the round advances. The first question announces the new round without exposing the remaining queue.
 
 Include the context needed to decide and a recommended answer. Phrase confirmations so "yes" accepts the recommendation; for choices, identify the recommended option.
 
 Example opening:
 
-> **Round 1, Question 1 of 5 - Output format**
+> **Round 1, Question 1 - Output format**
 >
 > CSV meets the agreed export requirements. I recommend CSV. Shall we use it?
 

package/build/Assets/Blueprints/skills/int-subagent-driven-dev/SKILL.md

@@ -41,17 +41,17 @@ flowchart TD
 
 ## Ticket workflow
 
-1. Read the feature spec, tickets, applicable instructions, glossary, and ADRs. Inspect `spindle sdd status --spec <path>` and `spindle sdd ready --spec <path>` to understand blockers, dependencies, and available work.
-2. Create a ticket for independently actionable work with `spindle sdd ticket create`. Fill its `[REQUIREMENTS]` and `[ACCEPTANCE CRITERIA]` placeholders. Use `spindle sdd ticket update` for tracker status, explicit blockers, and dependencies; the supported lifecycle is `open`, `in-progress`, and `closed`. Readiness is derived from status, blockers, and dependencies rather than stored as a separate triage state.
-3. Claim a ready ticket with `spindle sdd claim`. Dispatch implementation with `spindle sdd implement`; pass the worker the exact assignment and report destination. Submit its report with `spindle sdd submit --role implementation`.
+1. Read the feature spec, tickets, applicable instructions, glossary, and ADRs. Inspect `{{ computed.spindle_package_manager }} spindle sdd status --spec <path>` and `{{ computed.spindle_package_manager }} spindle sdd ready --spec <path>` to understand blockers, dependencies, and available work.
+2. Create a ticket for independently actionable work with `{{ computed.spindle_package_manager }} spindle sdd ticket create`. Fill its `[REQUIREMENTS]` and `[ACCEPTANCE CRITERIA]` placeholders. Use `{{ computed.spindle_package_manager }} spindle sdd ticket update` for tracker status, explicit blockers, and dependencies; the supported lifecycle is `open`, `in-progress`, and `closed`. Readiness is derived from status, blockers, and dependencies rather than stored as a separate triage state.
+3. Claim a ready ticket with `{{ computed.spindle_package_manager }} spindle sdd claim`. Dispatch implementation with `{{ computed.spindle_package_manager }} spindle sdd implement`; pass the worker the exact assignment and report destination. Submit its report with `{{ computed.spindle_package_manager }} spindle sdd submit --role implementation`.
 4. Run relevant tests and checks and record their actual outcomes against the current snapshot. TDD is not required, but verification is.
-5. Address implementation and verification gaps, then close the ticket with `spindle sdd ticket update --status closed` once its acceptance criteria are met. Do not use per-ticket accept or integrate steps.
+5. Address implementation and verification gaps, then close the ticket with `{{ computed.spindle_package_manager }} spindle sdd ticket update --status closed` once its acceptance criteria are met. Do not use per-ticket accept or integrate steps.
 
-If work is interrupted, inspect `spindle sdd status` and use `spindle sdd resume` to restore the recorded assignment. Preserve existing reports, findings, and evidence. Do not invent missing results or reset progress.
+If work is interrupted, inspect `{{ computed.spindle_package_manager }} spindle sdd status` and use `{{ computed.spindle_package_manager }} spindle sdd resume` to restore the recorded assignment. Preserve existing reports, findings, and evidence. Do not invent missing results or reset progress.
 
 ## Feature review and completion
 
-After every ticket is closed, establish current feature-level checks and request the comprehensive review with `spindle sdd review --scope delivery --inventory <json-array>`. The `sdd-reviewer` is the default reviewer. Add specialists only for justified objectives with `spindle sdd review require --scope delivery --type <agent-name>`; eligible names must be marked `canReview: true` in the Blueprint Catalog, and actual agent access must be confirmed before dispatch.
+After every ticket is closed, establish current feature-level checks and request the comprehensive review with `{{ computed.spindle_package_manager }} spindle sdd review --scope delivery --inventory <json-array>`. The `sdd-reviewer` is the default reviewer. Add specialists only for justified objectives with `{{ computed.spindle_package_manager }} spindle sdd review require --scope delivery --type <agent-name>`; eligible names must be marked `canReview: true` in the Blueprint Catalog, and actual agent access must be confirmed before dispatch.
 
 Submit every assigned review report against its exact assignment. Register findings from their report and snapshot. A blocking finding can name `--related-ticket`; once the complete review batch is submitted, that ticket is reopened so work can resume. Resolve blocking findings through ticket work and repeat any invalidated checks and reviews.
 

package/build/Assets/Blueprints/skills/int-subagent-driven-dev/references/corrective-rounds.md

@@ -38,7 +38,7 @@ adjudication rather than another automatic dispatch.
 
 ## C. Record objective and dispatch correction
 
-Use `spindle sdd correct --scope delivery` to record and dispatch the feature-level
+Use `{{ computed.spindle_package_manager }} spindle sdd correct --scope delivery` to record and dispatch the feature-level
 correction. Preserve prior attempts, reports, and report destinations.
 Serialize implementation edits and keep the assignment limited to the
 recorded objective.

package/build/Assets/Blueprints/skills/int-subagent-driven-dev/references/example-workflow.md

@@ -5,16 +5,16 @@ Markdown holds requirements and acceptance criteria; `sdd.json` holds tracker
 status and dependencies.
 
 1. Create a feature workspace and split independent work into tickets:
-   `spindle sdd create`, then `spindle sdd ticket create` for each ticket.
+   `{{ computed.spindle_package_manager }} spindle sdd create`, then `{{ computed.spindle_package_manager }} spindle sdd ticket create` for each ticket.
 2. Record the dependency with
-   `spindle sdd ticket update --ticket T-0002 --blocked-by T-0001`. Check `spindle sdd ready`:
+   `{{ computed.spindle_package_manager }} spindle sdd ticket update --ticket T-0002 --blocked-by T-0001`. Check `{{ computed.spindle_package_manager }} spindle sdd ready`:
    the prerequisite is ready and the dependent ticket is not.
 3. Claim and implement `T-0001`, submit its report, run and record relevant
-   checks, then close it with `spindle sdd ticket update --status closed`.
+   checks, then close it with `{{ computed.spindle_package_manager }} spindle sdd ticket update --status closed`.
 4. `T-0002` becomes ready because its dependency is closed. Implement and
    verify it in the same way, then close it.
 5. Record current feature-level required checks and request the comprehensive
-   review with `spindle sdd review --scope delivery`. Add only justified specialists.
+   review with `{{ computed.spindle_package_manager }} spindle sdd review --scope delivery`. Add only justified specialists.
 6. Submit every assigned report. Register findings from their report and
    snapshot. A blocking finding can reopen its related ticket; complete the
    correction, close the ticket again, and refresh stale checks and review.

package/build/Assets/Blueprints/skills/int-subagent-driven-dev/references/full-spec.md

@@ -7,16 +7,16 @@ checks, review assignments, findings, and corrections.
 
 ## Checks and review
 
-Inspect `spindle sdd status --spec <spec>` and `spindle sdd next --spec <spec>`. Establish
-required final checks with `spindle sdd checks require --scope delivery`, run them, and
+Inspect `{{ computed.spindle_package_manager }} spindle sdd status --spec <spec>` and `{{ computed.spindle_package_manager }} spindle sdd next --spec <spec>`. Establish
+required final checks with `{{ computed.spindle_package_manager }} spindle sdd checks require --scope delivery`, run them, and
 record actual results against the returned snapshot. Then dispatch the
 comprehensive review with
-`spindle sdd review --scope delivery --inventory <json-array>`. Its inventory must
+`{{ computed.spindle_package_manager }} spindle sdd review --scope delivery --inventory <json-array>`. Its inventory must
 cover the feature's current Git-derived changes.
 
 The `sdd-reviewer` is the default comprehensive reviewer. Before dispatch,
 record any justified specialist with
-`spindle sdd review require --scope delivery --type <agent-name> --details <objective>`.
+`{{ computed.spindle_package_manager }} spindle sdd review require --scope delivery --type <agent-name> --details <objective>`.
 Only catalog agents with `canReview: true` are eligible. Confirm that the
 controller can actually dispatch each selected agent; catalog eligibility does
 not guarantee harness access.
@@ -28,24 +28,24 @@ failed, unavailable, stale, or mismatched review blocks completion.
 ## Findings and correction
 
 Register findings from their assigned reports and snapshots with
-`spindle sdd finding create --scope delivery`. Delivery findings have feature-scoped
+`{{ computed.spindle_package_manager }} spindle sdd finding create --scope delivery`. Delivery findings have feature-scoped
 IDs, provenance, ruling history, and status. Use `--related-ticket <id>` for a
 finding that should return work to a specific ticket. A blocking linked finding
 reopens its ticket after the complete review batch is submitted; dependent
 tickets remain blocked until that ticket is closed again.
 
-Use `spindle sdd finding update --scope delivery` for explicit rulings. Deferring a
+Use `{{ computed.spindle_package_manager }} spindle sdd finding update --scope delivery` for explicit rulings. Deferring a
 blocker requires rationale, a follow-up reference, and an approved delivery
 requirements decision. Record that decision with
-`spindle sdd requirements decide --scope delivery` only after a requirements change
+`{{ computed.spindle_package_manager }} spindle sdd requirements decide --scope delivery` only after a requirements change
 and completed prior review. Approval invalidates earlier aggregate assignments.
 
 For actionable feature findings, follow [feature correction](./corrective-rounds.md)
-and use `spindle sdd correct --scope delivery` to record
+and use `{{ computed.spindle_package_manager }} spindle sdd correct --scope delivery` to record
 each independent correction attempt. Record passing checks against the changed
 feature snapshot and submit the implementation report before requesting a new
 feature review. Pause unproductive work, recurring failures, or requirements
-disagreement for adjudication. Resume with `spindle sdd resume --scope delivery`;
+disagreement for adjudication. Resume with `{{ computed.spindle_package_manager }} spindle sdd resume --scope delivery`;
 preserve existing assignments, attempts, evidence, and adjudication.
 
 ## Finish
@@ -59,14 +59,14 @@ the original comparison baseline is identified. Do not silently use the
 current `HEAD` after implementation; that could omit completed feature work
 from review.
 
-Finish with `spindle sdd finish --spec <spec> --author <author>`. Completion requires
+Finish with `{{ computed.spindle_package_manager }} spindle sdd finish --spec <spec> --author <author>`. Completion requires
 at least one ticket, every ticket closed, current passing required feature
 checks and reviews, and no unresolved delivery blockers. The retrospective
 policy is stored at feature creation: when required, attach a Markdown report
 with `--report`; otherwise it is optional. Any report must remain inside that
 feature's `reports/` directory.
 
-Use `spindle sdd status`, `spindle sdd next`, and
-`spindle sdd resume --scope delivery` to inspect blockers and
+Use `{{ computed.spindle_package_manager }} spindle sdd status`, `{{ computed.spindle_package_manager }} spindle sdd next`, and
+`{{ computed.spindle_package_manager }} spindle sdd resume --scope delivery` to inspect blockers and
 restore interrupted feature-level work. These commands do not close tickets or
 publish changes.

package/build/Assets/Blueprints/skills/int-testing-agent-guidance/SKILL.md

@@ -2,7 +2,7 @@
 name: int-testing-agent-guidance
 metadata:
   spindle:
-    version: 1.0.0
+    version: 1.0.1
 description: "{{ computed.internal_skill_description }}"
 user-invocable: false
 ---
@@ -32,7 +32,7 @@ Use this workflow for behavior-shaping changes to skills, agents, prompts, instr
 
 ## Expanded testing
 
-Use expanded testing when the user requests it or the skill is invoked with `--test`. This adds independent samples; it does not replace the core baseline and retest.
+Always run expanded testing for authoring tasks. It adds independent samples and does not replace the core baseline and retest.
 
 1. Freeze scenario prompts and observable pass criteria before dispatch. Cover each meaningful branch. For discipline-enforcing guidance, use at least three scenarios, each combining at least three pressures such as deadline, authority, sunk cost, or exhaustion.
 2. Run five independent read-only agents against the baseline. For a new document, provide no proposed guidance; for an edit, provide the current version. Each agent runs every scenario once and reports its concrete choices and rationalizations verbatim.

package/build/Assets/Blueprints/skills/int-writing-skills/SKILL.md

@@ -4,7 +4,7 @@ description: "{{ computed.internal_skill_description }}"
 user-invocable: false
 metadata:
   spindle:
-    version: 1.3.0
+    version: 1.3.1
 ---
 
 # Writing Skills
@@ -118,7 +118,7 @@ Compare observed behavior with the unchanged criterion. An unresolved failure se
 
 ### G. Refactor and deliver
 
-Prune duplication, stale material, and speculative rules. Retest after wording changes. Verify frontmatter, relative links, resource packaging, and any required version bump. Run expanded testing only when requested, including `--test`.
+Prune duplication, stale material, and speculative rules. Retest after wording changes. Verify frontmatter, relative links, resource packaging, and any required version bump. Always run expanded testing with `int-testing-agent-guidance`.
 
 **Complete when:** final validation passes or limitations are explicit, and the change is ready for authorized delivery. Commit, push, or open a PR only when requested.
 

package/build/Assets/Blueprints/skills/int-writing-skills/references/testing-skills.md

@@ -36,7 +36,7 @@ For discipline-enforcing guidance, consult [Persuasion principles](./persuasion-
 
 Rerun the same prompt and criterion with the full revised guidance in a fresh context. Check actual choices, resource loads, and artifacts. Correct remaining failures narrowly, then rerun after each wording change.
 
-Run expanded testing only when explicitly requested or when `--test` is present, using `int-testing-agent-guidance`. It adds coverage rather than replacing the focused baseline and retest.
+Always run expanded testing with `int-testing-agent-guidance`. It adds coverage rather than replacing the focused baseline and retest.
 
 | Testing pitfall                         | Required evidence                                               |
 | --------------------------------------- | --------------------------------------------------------------- |
@@ -45,4 +45,4 @@ Run expanded testing only when explicitly requested or when `--test` is present,
 | "There is no time"                      | Recorded validation or an explicit blocker, not claimed success |
 | "The output is close enough"            | The unchanged observable criterion passes                       |
 
-**Complete when:** the final focused scenario passes without unresolved failures, requested expanded testing is complete, or remaining failures and validation limits are explicitly reported.
+**Complete when:** the final focused scenario passes without unresolved failures, expanded testing is complete, or remaining failures and validation limits are explicitly reported.

package/build/Assets/Blueprints/skills/ref-php-laravel-saloon-api-integrations/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: ref-php-laravel-saloon-api-integrations
+description: "Use when building or testing Laravel API integrations with Saloon: connectors, requests, responses, failures, mocks, pools, or DTOs."
+metadata:
+  spindle:
+    version: 1.0.0
+---
+
+# Working with Saloon
+
+This skill covers the latest Saloon release and its Laravel plugin.
+
+## Integration boundaries
+
+A connector owns the base URL, shared authentication, default headers, and client configuration.
+A request owns its method, endpoint, and request-specific query, headers, and body.
+The connector sends the request.
+
+## Topic lookup
+
+Before writing code, read each reference whose condition matches the task.
+For combined tasks, read all matching references.
+
+| When working on                                                                     | Read                                                         |
+| ----------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| Base URL, shared authentication, default headers, timeouts, or client configuration | [Connectors](references/connectors.md)                       |
+| HTTP method, endpoint, inputs, query parameters, headers, or JSON body              | [Requests](references/requests.md)                           |
+| `send()` or `sendAsync()`, including promise handling                               | [Sending requests](references/sending-requests.md)           |
+| Status, headers, body parsing, response helpers, or custom response classes         | [Responses](references/responses.md)                         |
+| HTTP or connection failures, throwing, or custom failure detection and exceptions   | [Handling failures](references/handling-failures.md)         |
+| Tests, request assertions, mocks, or recorded fixtures                              | [Testing](references/testing.md)                             |
+| Concurrent batches, rate limits, keyed results, or pool handlers                    | [Concurrency and pools](references/concurrency-and-pools.md) |
+| Typed response mapping or DTO-driven request bodies                                 | [Data transfer objects](references/data-transfer-objects.md) |
+
+## Sources
+
+Use the [official documentation](https://docs.saloon.dev/) for API details beyond these references.
+Use the [latest release](https://github.com/saloonphp/saloon/releases/latest) for current changes.

package/build/Assets/Blueprints/skills/ref-php-laravel-saloon-api-integrations/references/concurrency-and-pools.md

@@ -0,0 +1,73 @@
+# Concurrency & Pools
+
+A pool sends independent requests concurrently through one connector.
+Use pools for batches such as fetching records by ID.
+Concurrency requires `GuzzleSender` (the default) or `HttpSender`.
+
+## Basic pool
+
+```php
+use Saloon\Exceptions\Request\FatalRequestException;
+use Saloon\Exceptions\Request\RequestException;
+use Saloon\Http\Response;
+
+$products = [];
+$failures = [];
+
+$pool = $connector->pool(
+    requests: function () use ($ids): Generator {
+        foreach ($ids as $id) {
+            yield $id => new GetProductRequest($id);
+        }
+    },
+    concurrency: 10,
+    responseHandler: function (Response $response, int|string $key) use (&$products) {
+        $products[$key] = $response->dtoOrFail();
+    },
+    exceptionHandler: function (FatalRequestException|RequestException $exception, int|string $key) use (&$failures) {
+        $failures[$key] = $exception instanceof RequestException
+            ? $exception->getResponse()->status()
+            : $exception->getMessage();
+    },
+);
+
+$pool->send()->wait();
+```
+
+`send()` returns a promise; call `wait()` before reading the results.
+
+## Requests
+
+Provide any of the following as the first argument or with `setRequests()`:
+
+- An array of `Request` or `PendingRequest` objects.
+- A generator, to keep memory low for large batches.
+- A closure or invokable class returning an array or generator, to run setup just before sending.
+
+Keys from arrays or generators reach both handlers, so key by ID to match results. Responses complete in any order; never rely on input order.
+
+## Concurrency
+
+The default is 5 requests in flight.
+Use the `concurrency` argument or `$pool->setConcurrency(10)` to change it. Both also accept a callable.
+Choose a value that respects the API's rate limits. A pool does not throttle requests over time.
+
+## Handlers
+
+- `responseHandler` / `withResponseHandler()`: receives each **successful** `Response`.
+- `exceptionHandler` / `withExceptionHandler()`: receives `RequestException` for 4xx/5xx responses and `FatalRequestException` for connection failures. HTTP failures always arrive here, even without `throw()` or `AlwaysThrowOnErrors`.
+
+Each pool holds one handler of each kind.
+For failure classification and custom exceptions, read [Handling failures](handling-failures.md).
+
+## Testing pools
+
+Use `MockClient` with pools. Mocked HTTP failures reach the exception handler.
+For offline setup and request assertions, read [Testing](testing.md).
+
+```php
+$connector->withMockClient(new MockClient([
+    MockResponse::make(['id' => 1, 'name' => 'Widget', 'price_cents' => 999], 200),
+    MockResponse::make(['message' => 'Not found'], 404),
+]));
+```

package/build/Assets/Blueprints/skills/ref-php-laravel-saloon-api-integrations/references/connectors.md

@@ -0,0 +1,99 @@
+# Connectors
+
+A connector represents one external API. Create one connector per integration under `app/Http/Integrations/<Api>/`.
+
+## Minimal connector
+
+Extend `Saloon\Http\Connector` and implement `resolveBaseUrl()`.
+
+```php
+use Saloon\Http\Connector;
+
+class InventoryConnector extends Connector
+{
+    public function resolveBaseUrl(): string
+    {
+        return 'https://inventory.example.com/api/v1';
+    }
+}
+```
+
+With the Laravel plugin installed, `php artisan saloon:connector` scaffolds one.
+
+## Constructor arguments and authentication
+
+Pass instance-specific values through the constructor. Put shared bearer authentication in `defaultAuth()`.
+
+```php
+use Saloon\Contracts\Authenticator;
+use Saloon\Http\Auth\TokenAuthenticator;
+use Saloon\Http\Connector;
+
+class InventoryConnector extends Connector
+{
+    public function __construct(
+        protected readonly string $baseUrl,
+        protected readonly string $token,
+    ) {}
+
+    public function resolveBaseUrl(): string
+    {
+        return $this->baseUrl;
+    }
+
+    protected function defaultAuth(): ?Authenticator
+    {
+        return new TokenAuthenticator($this->token);
+    }
+}
+
+$connector = new InventoryConnector(config('services.inventory.url'), config('services.inventory.token'));
+```
+
+`TokenAuthenticator` sends `Authorization: Bearer <token>`.
+Load credentials from configuration or secrets. Never hard-code production credentials.
+
+## Default headers
+
+Override `defaultHeaders()` for headers every request needs. Request headers are merged on top.
+
+```php
+protected function defaultHeaders(): array
+{
+    return [
+        'Accept' => 'application/json',
+        'Content-Type' => 'application/json',
+    ];
+}
+```
+
+Change headers on an instance with `$connector->headers()->add('X-Tenant', 'acme');`.
+
+## Timeouts
+
+Defaults are a 10-second connection timeout and a 30-second request timeout.
+Use `HasTimeout` on a connector for shared timeouts, or on a request for endpoint-specific timeouts.
+
+```php
+use Saloon\Traits\Plugins\HasTimeout;
+
+class InventoryConnector extends Connector
+{
+    use HasTimeout;
+
+    protected int $connectTimeout = 60;
+
+    protected int $requestTimeout = 120;
+}
+```
+
+## HTTP client config
+
+The default sender is Guzzle. Pass Guzzle request options through `defaultConfig()` or `$connector->config()->add(...)`.
+
+```php
+public function defaultConfig(): array
+{
+    return ['verify' => true];
+}
+```