Save this content to: AGENTS.md

# AGENTS Guide

## Purpose
- This repository is a small PHP SDK for the Tabstack REST API (`juststeveking/tabstack`).
- The public entrypoint is `JustSteveKing\Tabstack\Tabstack`; resources are exposed via `agent()`, `extract()`, and `generate()`.

## Repo Map (read these first)
- `composer.json`: runtime/dev dependencies and the canonical `composer` scripts.
- `src/Tabstack.php`: SDK root object, client wiring, base URI, and `send()` transport boundary.
- `src/Concerns/HasTabstackClient.php`: shared request/stream builders for all resources.
- `src/Resources/*.php`: endpoint-specific resource classes.
- `phpstan.neon` and `pint.json`: static analysis and formatting rules.

## Architecture and Flow
- `Tabstack::make(string $apiKey)` constructs a PSR-18 client via `Psr18ClientDiscovery` and sets base URI to `https://api.tabstack.com/v1`.
- Resource classes use `HasTabstackClient` to build PSR-7 requests (`request(Method $method, string $uri)`) and payload streams (`payload(string $payload)`).
- Requests should be created in resource methods, then sent through `Tabstack::send(RequestInterface $request)`.
- HTTP method values come from `JustSteveKing\Tools\Http\Enums\Method` (from `juststeveking/sdk-tools`).

## Project-Specific Conventions
- Use `declare(strict_types=1);` in all PHP files (already used across `src/`).
- Prefer named arguments for constructor/function calls (`Tabstack::make`, `HasTabstackClient::request`).
- Keep resources thin and endpoint-focused; shared request/payload logic belongs in `HasTabstackClient`.
- Follow existing API path style like `"/automate"` in `src/Resources/Agent.php`.

## Developer Workflow
- Format check: `composer lint` (Pint in test mode).
- Auto-format: `composer pint`.
- Static analysis: `composer stan` (PHPStan level 10 on `src`).
- Tests: `composer test` (currently no test files under `tests/`).

## Current State / Implementation Notes
- Resource surface exists but is incomplete: `Extract::json()`, `Extract::markdown()`, `Generate::json()`, and `Agent::research()` are stubs.
- `Agent::automate()` is partially implemented and currently syntactically incomplete; fix it before extending adjacent code.
- There is no dedicated exception/response abstraction in this package yet; methods currently work directly with PSR request/response types.

## Adding New Endpoints (recommended pattern)
- Add method to the relevant resource in `src/Resources/`.
- Build request via `$this->request(method: Method::..., uri: '/path')`.
- Encode JSON payload string (if needed) and wrap with `$this->payload(...)`.
- Send through `$this->tabstack->send($request)` and return a PSR response (or clearly documented shape).