docs(studio): add the apps/ agent contract and Studio rules

[peppescg]

Summary

This PR adds the agent contract for the Studio workspace (apps/): a lean
apps/AGENTS.md with its CLAUDE.md symlink, one pointer from the root
AGENTS.md, and three path-scoped rules under .claude/rules/. It changes
documentation only; no code under apps/ changes. It is the first of two PRs for
#1775. The skills follow in a separate PR.

What's in it

File	Content
apps/AGENTS.md, apps/CLAUDE.md (symlink)	The task studio:* entry points and their traps: task test and task lint skip Studio, the approval journey and the integration suite need bin/mecated, and how to run one Playwright journey. The generated files (contracts/openapi.json, contracts/src/generated/, web/src/routeTree.gen.ts) and how each is regenerated. The boundaries: the BFF owns the data the UI shows, the prototype's stack/08-tooling branch owns the look (#2210), the BFF uses the checked-out SDK by package name only, and MECATL_* describes the target while STUDIO_* configures Studio. Links to the rules. The screenshots a UI PR carries, and how to capture them with the offline Playwright fixtures (fixed clock, SSE handlers, and the output directory Playwright empties on each run).
.claude/rules/studio-bff.md	Scoped to apps/server/** and apps/contracts/**. The Hono route, Zod schema, and problem-details shape, route tests with createApp() and csrfHeaders(), and the BFF security invariants.
.claude/rules/studio-web.md	Scoped to apps/web/src/**. TanStack file-route naming, feature folders, data through the generated client, the shadcn/ui primitives (#2201), the 500px breakpoint with its guard test, and the 760px chat-list pivot. Touch-target size is left to #2271.
.claude/rules/studio-tests.md	Scoped to Studio test files, apps/web/e2e/**, and apps/server/test/**. The no-isolation Vitest rules that Biome enforces, the offlineBff Playwright fixture, the daemon-backed suites, and pinning tests in their own commit first.
AGENTS.md	One pointer to apps/AGENTS.md, in the same sentence as the engine/, internal/, and website/ pointers.

Every command, path, and invariant was checked against the Taskfiles, the
package.json scripts, the CI studio job, and the code it describes. Where the
list in #1775 differs from the code, the contract follows the code:

• SDK. Studio agent contract: apps/AGENTS.md, skills, and web/server rules #1775 lists "published @stacklok-oss/mecatl-sdk only, never
  sdk/typescript". Since feat: add execution templates with platform-managed identity #2219, the BFF builds the checked-out sdk/typescript
  through a frozen file: dependency and imports it by package name only
  (apps/README.md, docs/architecture/api-surface.md,
  apps/server/src/sdk-source.test.ts). The contract states that rule.
• Feature folders. Features import each other today (for example memory
  imports from settings, and chat from shortcuts), so the web rule says where
  code lives and leaves the boundary decision to Studio app structure: layout decision and the mechanical move #1777.
• fetch. "No fetch outside lib/api-client" is written as what the code
  does: data requests go through the generated client, configured once in
  lib/api-client.ts. No lint rule enforces it.
• Left out until decided: the size of the compact controls ported from the
  prototype (Studio: touch target size of compact controls (44px rule vs prototype density) #2271, linked from the web rule) and the Button API (Studio: use shadcn/ui primitives like the prototype and SEP (no custom components) #2201).

Decisions taken

• One apps/AGENTS.md for now, with a CLAUDE.md symlink beside it, as at
  the root and in engine/. A separate apps/web/AGENTS.md is revisited after
  the structure work in Studio app structure: layout decision and the mechanical move #1777.
• Path-scoped rule files under .claude/rules/ hold the conventions that
  apply to specific paths, with the same front matter and paths: scoping as
  test-isolation.md and wire-api-compatibility.md. apps/AGENTS.md stays a
  lean correction file that links to them.

What's left

• The skills under .claude/skills/ (add a Studio surface and touch Studio
  configuration) come in a later PR. Studio agent contract: apps/AGENTS.md, skills, and web/server rules #1775 names to-acceptance-plan,
  plan-orchestrate, and test-writer as the bar; chore: delete ADRs, acceptance plans, and process scaffolding #2105 removed those skills, so
  that PR takes its bar from the current set.
• The Studio agent contract: apps/AGENTS.md, skills, and web/server rules #1775 acceptance evidence (an agent given "add surface X" produces the right
  file set from the contract alone) is recorded once the skills exist.

Screenshots

No UI change: documentation only.

Verification

• task docs passes. matlatl reports 189 documents, 1828 references, 0 broken
  links, 0 broken anchors, 0 orphans, and 0 unreachable. The instruction-file
  check passes: each rule is at most 25 lines, apps/AGENTS.md is under 200 lines
  with its CLAUDE.md symlink, and every task name it mentions exists.
• task generate passes with no changes. Studio agent contract: apps/AGENTS.md, skills, and web/server rules #1775 mentions task generate for
  llms.txt, but the repository no longer commits an llms.txt; the site build's
  plugin produces one from user-docs/, which this PR doesn't touch.
• An independent read-only fact-check compared every claim with the code; its
  corrections are in the commit.
• Commands run to check the contract: pnpm run generate and tsr generate
  reproduce the committed files with no diff.
  pnpm run test:browser --list <SPEC> --project=<NAME> selects one journey,
  while with -- Playwright ignores the arguments and selects all 148 tests. A
  full journey run without bin/mecated passed 114 tests and could not run the
  approval journey.

Part of #1775
Part of #1774

🤖 Generated with Claude Code