Getting ready for 2.0.0 release

Author: ddebowczyk

ADDING-PACKAGE.md

@@ -4,6 +4,8 @@ This monorepo treats each package as a first-class split package.
 
 Use this checklist when adding a new package.
 
+This is the sequence that actually works.
+
 ## 1. Create The Package
 
 Create the package directory under `packages/<name>` with:
@@ -21,6 +23,8 @@ For docs, keep the initial structure small:
 - `docs/overview.md`
 - `docs/quickstart.md`
 
+The package must have a valid `composer.json` before it can be published to Packagist.
+
 ## 2. Register It In The Monorepo
 
 Add the package to [packages.json](/Users/ddebowczyk/projects/instructor-php/packages.json):
@@ -41,6 +45,8 @@ Then update:
 - [CONTENTS.md](/Users/ddebowczyk/projects/instructor-php/CONTENTS.md)
 - [CONTRIBUTOR_GUIDE.md](/Users/ddebowczyk/projects/instructor-php/CONTRIBUTOR_GUIDE.md)
 - any docs registries under `packages/*/resources/config/docs.yaml` or `.yml`
+- docs landing pages if the package should appear there
+- examples/docs pointers if this package splits functionality out of another package
 
 If the package adds public docs, give it:
 
@@ -57,6 +63,8 @@ Run:
 
 This regenerates the package matrix in `.github/workflows/split.yml` from `packages.json`.
 
+Do not edit the split matrix by hand unless the generator is broken.
+
 ## 4. Create The GitHub Repo
 
 Create the split repository with `gh`:
@@ -73,35 +81,81 @@ Verify it exists:
 gh repo view cognesy/instructor-http-pool --json name,url,visibility
 ```
 
-## 5. Add The Package To Packagist
+## 5. Make Sure The Split Repo Has Real Package Contents
+
+Packagist will reject a new repo if `main` does not contain `composer.json`.
+
+Before submitting to Packagist:
+
+- push the monorepo changes that introduce the package, then let the split workflow publish it
+- or bootstrap the split repo manually with the package contents if you need it immediately
+
+The important check is:
+
+```bash
+gh repo view cognesy/instructor-http-pool --web
+```
+
+Then confirm the repo `main` branch already contains:
+
+- `composer.json`
+- `src/`
+- `README.md`
+
+## 6. Add The Package To Packagist
+
+Preferred path in this repo: Packagist API token from `.env`.
+
+```bash
+PACKAGIST_API_USERNAME=$(sed -n "s/^PACKAGIST_API_USERNAME='\\(.*\\)'$/\\1/p" .env)
+PACKAGIST_API_TOKEN=$(sed -n "s/^PACKAGIST_API_TOKEN='\\(.*\\)'$/\\1/p" .env)
+
+curl -X POST \
+  -H 'content-type: application/json' \
+  "https://packagist.org/api/create-package?username=${PACKAGIST_API_USERNAME}&apiToken=${PACKAGIST_API_TOKEN}" \
+  -d '{"repository":{"url":"https://github.com/cognesy/instructor-http-pool"}}'
+```
+
+Expected response:
 
-Default path: manual.
+```json
+{"status":"success"}
+```
+
+Then verify:
+
+```bash
+curl -I https://packagist.org/packages/cognesy/instructor-http-pool
+curl -I https://repo.packagist.org/p2/cognesy/instructor-http-pool.json
+```
+
+Manual fallback:
 
 1. Open `https://packagist.org/packages/submit`
-2. Submit the split repository URL, for example:
-   `https://github.com/cognesy/instructor-http-pool`
+2. Submit the split repository URL
 3. Confirm the package name from `composer.json`
-4. In Packagist package settings, enable the GitHub hook or auto-update
-
-If you want to automate this later, use a Packagist token and their API. That is not part of the current default workflow.
+4. Enable the GitHub hook or auto-update
 
-## 6. Verify The Package Is Discoverable
+## 7. Verify The Package Is Discoverable
 
 Check:
 
 - docs autodiscovery sees `packages/<name>/docs`
 - split workflow contains the package
 - root Composer autoload includes the namespace
 - package `composer.json` is valid
+- Packagist can resolve the package
+- the split repository exists and is public
 
 Useful checks:
 
 ```bash
 composer validate packages/http-pool/composer.json
 rg "http-pool" packages.json .github/workflows/split.yml packages/*/resources/config
+gh repo view cognesy/instructor-http-pool --json url,defaultBranchRef
 ```
 
-## 7. Run Focused QA
+## 8. Run Focused QA
 
 At minimum:
 
@@ -120,4 +174,5 @@ composer test
 
 - `packages.json` is the source of truth for split-package registration.
 - `update-split-yml.sh` should be used instead of editing `.github/workflows/split.yml` by hand.
+- Packagist submission depends on the split repo, not the monorepo. If the split repo is empty, submission fails.
 - Keep package docs minimal at first. Add more only when the API stabilizes.

builds/docs-build/packages/agent-ctrl/10-opencode-bridge.mdx

@@ -25,7 +25,7 @@ $result = SandboxCommandExecutor::forOpenCode()->execute($spec);
 $response = (new ResponseParser())->parse($result, OutputFormat::Json);
 
 echo $response->messageText();
-// @doctest id="5913"
+// @doctest id="85e6"
 ```
 
 ## Session Handling

builds/docs-build/packages/agent-ctrl/2-getting-started.mdx

@@ -7,7 +7,7 @@ description: 'Run your first prompt with AgentCtrl.'
 
 ```bash
 composer require cognesy/agent-ctrl
-# @doctest id="4be1"
+# @doctest id="4014"
 ```
 
 You need at least one CLI binary installed and authenticated (`claude`, `codex`, or `opencode`).
@@ -20,7 +20,7 @@ use Cognesy\AgentCtrl\AgentCtrl;
 $response = AgentCtrl::codex()->execute('Summarize this repository.');
 
 echo $response->text();
-// @doctest id="6a9a"
+// @doctest id="a8b5"
 ```
 
 ## Runtime Agent Selection
@@ -31,5 +31,5 @@ use Cognesy\AgentCtrl\Enum\AgentType;
 
 $agent = AgentType::from('codex');
 $response = AgentCtrl::make($agent)->execute('List top risks in this code.');
-// @doctest id="1033"
+// @doctest id="0841"
 ```

builds/docs-build/packages/agent-ctrl/3-streaming.mdx

@@ -15,7 +15,7 @@ $response = AgentCtrl::openCode()
     ->onComplete(fn(AgentResponse $response) => print("\n[done]\n"))
     ->onError(fn(string $message, ?string $code) => print("\n[error:$message]\n"))
     ->executeStreaming('Explain this package architecture.');
-// @doctest id="846c"
+// @doctest id="2e88"
 ```
 
 `execute()` is a non-streaming convenience method.

builds/docs-build/packages/agent-ctrl/4-session-management.mdx

@@ -13,7 +13,7 @@ use Cognesy\AgentCtrl\AgentCtrl;
 $response = AgentCtrl::codex()
     ->continueSession()
     ->execute('Continue from the previous plan and apply step 2.');
-// @doctest id="2c93"
+// @doctest id="2e32"
 ```
 
 ## Resume Specific Session
@@ -29,7 +29,7 @@ if ($sessionId !== null) {
         ->resumeSession((string) $sessionId)
         ->execute('Now implement the first migration.');
 }
-// @doctest id="800c"
+// @doctest id="6cdc"
 ```
 
 `sessionId()` returns `AgentSessionId|null`.

builds/docs-build/packages/agent-ctrl/5-agent-options.mdx

@@ -31,7 +31,7 @@ $response = AgentCtrl::claudeCode()
     ->withPermissionMode(PermissionMode::BypassPermissions)
     ->withMaxTurns(10)
     ->execute('Refactor this service to remove duplication.');
-// @doctest id="6fa5"
+// @doctest id="4802"
 ```
 
 ## Codex
@@ -56,7 +56,7 @@ $response = AgentCtrl::codex()
     ->withSandbox(SandboxMode::WorkspaceWrite)
     ->fullAuto()
     ->execute('Write tests for this controller.');
-// @doctest id="a8e7"
+// @doctest id="65a9"
 ```
 
 ## OpenCode
@@ -77,5 +77,5 @@ $response = AgentCtrl::openCode()
     ->withAgent('coder')
     ->withTitle('Repository cleanup')
     ->execute('Find dead code and propose removals.');
-// @doctest id="3b70"
+// @doctest id="40d1"
 ```

builds/docs-build/packages/agent-ctrl/6-response-object.mdx

@@ -38,5 +38,5 @@ if ($response->isSuccess()) {
 
 echo $response->exitCode;
 echo $response->sessionId() !== null ? 'has session' : 'no session';
-// @doctest id="e4bd"
+// @doctest id="f4c2"
 ```

builds/docs-build/packages/agent-ctrl/7-troubleshooting.mdx

@@ -21,7 +21,7 @@ When using `inDirectory('/path')`, the directory must exist.
 $response = AgentCtrl::claudeCode()
     ->inDirectory('/existing/path')
     ->execute('List top 3 refactors.');
-// @doctest id="4e6d"
+// @doctest id="1b6d"
 ```
 
 ## Stream Parse Failures

builds/docs-build/packages/agent-ctrl/8-claude-code-bridge.mdx

@@ -25,7 +25,7 @@ $result = SandboxCommandExecutor::forClaudeCode()->execute($spec);
 $response = (new ResponseParser())->parse($result, OutputFormat::Json);
 
 echo $response->messageText();
-// @doctest id="7191"
+// @doctest id="f314"
 ```
 
 ## Streaming
@@ -38,7 +38,7 @@ $request = new ClaudeRequest(
     outputFormat: OutputFormat::StreamJson,
     includePartialMessages: true,
 );
-// @doctest id="319a"
+// @doctest id="f8d6"
 ```
 
 ## Key Types

builds/docs-build/packages/agent-ctrl/9-codex-bridge.mdx

@@ -27,7 +27,7 @@ $result = SandboxCommandExecutor::forCodex()->execute($spec);
 $response = (new ResponseParser())->parse($result, OutputFormat::Json);
 
 echo $response->messageText();
-// @doctest id="9a99"
+// @doctest id="8f4d"
 ```
 
 ## Streaming