Add global instructions config for the Studio Code agent

[youknowriad]

Why

A user asked me for the possibility to move his instructions/context from a conversation to another. I think what we really need ultimately is a wp.com user tied knowledge base, but there's a small thing we could provider users without building all of that, an instructions file config where users can provide global instructions injected in the Studio Code system prompt.

Related issues

• Related to the Studio Code knowledge-base direction (no linked issue yet).

How AI was used in this PR

Designed and implemented in a Claude Code session pair-driven by @youknowriad: exploration, implementation, tests, and the eval were AI-authored, with direction and design decisions (file location, remote-session inclusion, dedicated settings tab, local-UI support) made by the human. A four-angle AI cleanup review pass is being applied as a follow-up commit on this branch.

Proposed Changes

Users can now give the Studio Code agent standing, global instructions — preferences that apply to every conversation across all sites, e.g. "always answer in French" or "I prefer light background colors". Until now, such preferences had to be repeated in every session.

• Instructions live in a plain markdown file at ~/.studio/knowledge/instructions.md, editable in a new Studio Code settings tab in the classic desktop UI, the agentic UI, and the studio ui web UI (served through a small local-server API). Power users can edit the file directly; edits take effect on the next agent message.
• The instructions are injected into the agent system prompt for both local and remote (WordPress.com) sessions, framed so they cannot override safety or validation guardrails, size-capped (16 KB, truncated with a visible notice) so they can't crowd out the rest of the prompt, and resilient (a missing or unreadable file never breaks the agent).
• The knowledge/ directory is the deliberate seed of a future knowledge base: sibling markdown files with an injected index and on-demand retrieval can be added later without migrating anything.
• The hosted (cloud) web UI hides the tab — there's no user filesystem there.

Testing Instructions

1. npm run cli:build && npm start, open Settings → Studio Code, save an easily observable instruction (e.g. "End every reply with the word BANANA"), start a new Studio Code conversation, and confirm the agent follows it.
2. Same flow in the agentic UI (Settings → Studio Code tab).
3. Local web UI: npm run build:local --workspace=apps/ui && npm run cli:build && node apps/cli/dist/cli/main.mjs ui → Settings → Studio Code.
4. Terminal agent: node apps/cli/dist/cli/main.mjs ai "say hello" picks up the same file.
5. Automated: npm test -- packages/common/ai/tests/global-instructions.test.ts apps/cli/ai/tests/system-prompt.test.ts, and npm run eval -- --filter-pattern "global instructions" (requires studio auth login; passed locally).

Pre-merge Checklist

• Have you checked for TypeScript, React or other console errors?

🤖 Generated with Claude Code

[wpmobilebot]

📊 Performance Test Results

Comparing a6b2cff vs trunk

app-size

Metric	trunk	a6b2cff	Diff	Change
App Size (Mac)	1361.91 MB	1361.95 MB	+0.04 MB	⚪ 0.0%

site-editor

Metric	trunk	a6b2cff	Diff	Change
load	1087 ms	1121 ms	+34 ms	⚪ 0.0%

site-startup

Metric	trunk	a6b2cff	Diff	Change
siteCreation	6565 ms	6537 ms	28 ms	⚪ 0.0%
siteStartup	2395 ms	2395 ms	0 ms	⚪ 0.0%

---

Results are median values from multiple test runs.

Legend: 🟢 Improvement (faster) | 🔴 Regression (slower) | ⚪ No change (<50ms diff)

[sejas]

Works great and I like the idea of having global Instructions. This PR will close STU-1725

Some minor suggestions to consider:

• What if we call it AGENTS.md? I know it goes into the instructions, which will steer the agent even more, but it also accomplishes the same goal of customizing the agent.
• The save state is too fast 😆, and it feels uncertain if it worked or not. I suggest following the same pattern as other modals, we could delay the saving action to see the progress button and closing the modal after it finishes. A small success message could be a good alternative.
• Currently we truncate the instructions to USER_INSTRUCTIONS_MAX_LENGTH, but we don't notify about this limitation to the user in the Settings modal. I suggest adding limit to the text area or even a count character or an error message. I know users could edit the file directly, but the UI should set better expectations about the existing limit.

Otherwise LGTM. Thanks for adding this feature!

Classic	Agentic

Instructions file updated:

Instructions in action:

Saving doesn't communicate the success:

agent-sintructions.mp4

[sejas]

We could consider adding a limit in the Settings text area or some kind of indicator.