Creating Contexts

Step-by-step guide to creating Context Documents in CodeCourier, writing effective markdown content, publishing your first version, and linking Contexts to personas and session types.

8 min read

contextscreatemarkdown

This guide walks through creating a Context Document from scratch - from navigating to the Contexts page, writing well-structured markdown content, publishing your first version, and finally linking the Context to the session types or personas that should receive it.

Navigating to the Contexts Page

Contexts are accessed from the project sidebar. Look for the Contexts entry in the left navigation panel. If you do not see it, ensure you have at least Member access to the project. The Contexts page is located at /p/{projectId}/context.

The page lists all existing Contexts in the project, showing each Context’s name, description, number of published versions, and the active version’s publish date. If no Contexts have been created yet, you will see an empty state with a prominent Create Context button.

Creating a New Context

Open the Create dialog

Click + Create Contextin the top-right corner of the Contexts page. A dialog opens asking for the Context’s basic metadata.

Enter a name (required)

Give the Context a descriptive name that reflects its subject matter. Good names communicate intent at a glance:

Project Architecture - full stack overview and conventions
Coding Standards - style rules, TypeScript configuration, linting
Security Checklist - OWASP requirements, input sanitization rules
API Reference - key endpoints, authentication patterns, rate limits
Testing Conventions - Vitest setup, mock patterns, coverage targets

Names must be non-empty and are validated on submission. You can rename the Context later from its detail page.

Add a description (optional but recommended)

The description appears on the Contexts list page and in binding dropdowns throughout Project Settings. A clear description helps team members understand which Context to link to a session type without having to open and read the full content. For example:

“Full architectural overview of the Next.js + Convex + Clerk stack, including file conventions and data flow. Inject into all Designer sessions.”

Submit the form

Click Create. You are redirected to the Context detail page where you can write the full markdown content and publish your first version.

Writing the Context Content

The Context detail page contains a full-featured markdown editor. The content you write here is exactly what gets injected into sandbox sessions. Write it the same way you would write a CLAUDE.md file - clearly structured, using headers for navigation and bullet points for scannable rules.

What to Include

Effective Context content is specific and actionable. Agents perform best when they have concrete, unambiguous rules rather than vague guidelines. Structure your content with:

An overview section describing the technology stack at a high level
File convention sections listing where different types of files live
Coding standards covering naming, patterns, and anti-patterns to avoid
Key constraints using explicit “never” and “always” language
Important dependencies or configuration that agents need to be aware of

Example Context Content

Below is an example of a well-written Project Architecture Context for a full-stack TypeScript application:

project-architecture-context.md

# Project Architecture

This is a Next.js 16 application with:
- **Frontend**: React 19, TypeScript, Tailwind CSS, shadcn/ui
- **Backend**: Convex (reactive database + server functions)
- **Auth**: Clerk

## Coding Standards
- Always use TypeScript strict mode
- Prefer server components over client components
- Use Convex mutations for all data writes
- Never use `dangerouslySetInnerHTML` without sanitization

## File Conventions
- Components: PascalCase in `/components/`
- Hooks: camelCase with `use` prefix in `/hooks/`
- Utils: camelCase in `/lib/`

## Convex Rules
- Never use `.collect()` on large tables - use `.take(N)` or paginate
- Batch work goes to `ctx.scheduler.runAfter` to avoid timeout
- Mutations validate input with Convex validators, not Zod

## Next.js Specifics
- The middleware file is `proxy.ts`, NOT `middleware.ts`
- All API routes live in `/app/api/`
- Use `generateStaticParams` for static paths, not `getStaticPaths`

## Testing
- Unit tests: Vitest with `@testing-library/react`
- E2E tests: Playwright in `/e2e/`
- Run `bun test` before every commit

Keep Content Focused

Resist the temptation to dump your entire codebase wiki into a single Context. Agents have finite context windows. Write focused, relevant information and create separate Contexts for distinct domains (architecture, security, testing) rather than one enormous document.

Publishing Your First Version

Write or paste your content

Enter the markdown content in the editor on the Context detail page. The editor supports live preview so you can see how the content will render.

Click Publish

Click the Publish button to create version 1 of this Context. On publish, CodeCourier creates a new version record with status active and records the current timestamp and your user identity as the publisher.

Verify the active version

After publishing, the page displays the version number and publish date in the version history panel. The badge on the active version reads Active. This is the version that will be injected into sandboxes.

Unpublished Changes

If you edit the content without clicking Publish, your changes are saved as a draft. The active version in sandboxes remains the previously published version until you publish again. The editor shows an “Unpublished changes” indicator when your draft differs from the active version.

Viewing Version History

The Version History panel on the Context detail page lists every published version in reverse-chronological order. Each entry shows:

Version number (v1, v2, v3, …)
Publish timestamp
Who published it (user display name)
Active or inactive status badge

Click any version to view its content in read-only mode. This lets you compare the current active version against historical versions to understand what changed.

Linking a Context to a Persona

To bind a Context to a specific persona, navigate to the persona’s detail page at/p/{projectId}/personas/{personaId} and open the Contexttab. From there, use the dropdown to select the Context you want this persona to use. Once saved, every session run by this persona will inject the persona’s bound Context instead of the session-type default.

Persona Override Takes Precedence

Setting a Context on a persona overrides the session-type default. If you want a persona to use no Context (even when the session type has a default), you must explicitly clear the persona’s Context binding rather than leaving it unset - an unset persona binding falls through to the session-type default.

Linking a Context to a Session Type

Session-type bindings are managed from Project Settings. Each session type has its own setup tab:

Answering Setup - /p/{id}/answering-setup
Issues Setup - /p/{id}/issues-setup
Learning Setup - /p/{id}/learning-setup
Merging Setup - /p/{id}/merging-setup
Evaluator Setup - /p/{id}/evaluator-setup
Judge Setup - /p/{id}/judge-setup

On each setup tab, find the Context field and select the Context you want all sessions of that type to receive by default. The binding is saved immediately on selection.