Context sources
The documents the agent reads before it plans: what to attach, at which level, and how inheritance works.
Context is the material the agent reads before it writes anything: your PRDs, research, support transcripts, regulations, API documentation, meeting notes.
It is the single highest-leverage thing you can give it. An agent with no Context writes a plausible plan about software in general; an agent with your Context writes a plan about your business.
Discuss a source
Open Comments from the document viewer. A context discussion belongs to the plan where you started it, even when the source is shared across plans. That plan's owner receives updates. Readers can comment and suggest edits; accepting a change still requires permission to maintain the source. Check whether a suggestion applies to the readable copy or an external original. See Comments and suggested edits.
Three levels, and they flow down
| Attach at | When |
|---|---|
| Team | True for everything you build: how you work, your tone, your standards. |
| Project | True for this product: its PRD, its architecture, its customers. |
| Plan | Only for this piece of work: the regulation, the vendor's docs, the ticket thread. |
Context flows downward. A plan sees its own sources, plus its project's, plus your team's. A sub-plan also inherits everything above it, read-only.
Nothing flows upward or sideways. A project does not read its plans' sources, and sibling plans never see each other's.
Choosing the level
Attach as high as the material is true, and no higher.
A document at Team level reaches every plan in every project, which is right for "how we write release notes" and wrong for "the Q3 pricing memo". The cost of attaching too high is not storage, it is that every unrelated plan now reads it.
If a piece of work needs its own sources, that is the signal it should be a sub-plan rather than more Specs in the current one. Specs cannot hold Context; plans can. See Sub-plans and dependencies.
What you can upload
Drop a file into any Context tree, or use plansmith context add. Plansmith reads the document and
keeps your original.
| Format | What the agent reads |
|---|---|
.pdf | The text, with headings and tables recovered from the layout. |
.docx | The document converted to markdown, with its tables, and its pictures, each with a written description where one can be made. |
.doc | An older Word document converted to markdown the same way, with its headings, lists and tables, and its pictures described like a .docx's. Footnotes, endnotes and text boxes are read, with their numbers; headers and footers are skipped, since they repeat on every page. A picture that can't be shown here, such as an old Windows drawing or an embedded spreadsheet, gets a short note where it sits. Up to 4 MB. |
.xlsx | Each sheet as a table, with its header row, dates read as dates and formula cells as their result. |
.pptx | Each slide's title, bullets, tables, pictures (described the same way) and speaker notes. |
.csv | The rows as a table. |
.md, .txt | The file, as it is. |
.yaml, .json | The file, byte for byte. Structure is the content, so nothing rewrites it. |
.xml, .xsd, .xsl, .xslt | The file exactly as written, read in its own character encoding. A schema's or stylesheet's references are never followed, and your original is kept for download. |
.html | The document converted to markdown, with headings, lists and tables intact. |
.svg | The diagram's title, description and every text label. |
| Images | A written description of the picture. |
Recordings (.mp4, .mov, .webm) | A transcript with timestamps and speaker labels. |
Up to 25 MB per file, or 2 GB for a recording.
Your original file
The table above is what the agent reads. Your own file is kept too, and you can always get it back.
Open any uploaded source and the Properties tab shows what you added: its name, what kind of file it is, and how big it is. Download original in the header hands back the exact bytes you uploaded, under the name you gave them.
A PDF also gets a second tab, Content (original), which shows the document itself, page by page, in the drawer, beside the text the agent reads. Word documents, decks and spreadsheets have no second tab, because no browser can render them: download the file and open it in the application that made it.
- Files added before this shipped kept their bytes but not their name, so their Properties tab says stored name and shows the name as it was saved. Everything else works normally.
- Recordings play where they always have and are not downloadable one at a time yet. Use
plansmith context downloadto get a whole scope as an archive. - Sources you added as a URL or pasted as text have no original file, so they show none of this.
From the API or the CLI:
# What this source is, including its original file
plansmith context get SOURCE_ID
# Save the file exactly as you uploaded it
plansmith context get SOURCE_ID --download ./review.pdfGET /v1/context/{sourceId}/file is the same thing over HTTP, and it exists at the project and
plan addresses too. An existing destination is never overwritten unless you pass --force.
Recordings
Drop in a customer call, a Loom walkthrough or a demo, up to 2 GB and 2 hours. Plansmith writes the transcript in the background, so the source appears in your tree straight away and tells you where it is up to: "Queued for transcription" while it waits its turn, "Transcribing…" once it is being read, and "Retrying" with the attempt number if the first read failed. It is usually ready within a minute or two. Open it and the video plays above the transcript; click a timestamp to jump there.
Each speaker is labelled, and the transcript stays in whatever language people are speaking. It is never translated.
The transcript is what the agent reads, so it plans from a call the same way it plans from a document. Each transcription is billed as usage, on its own line, priced by the length of the recording.
A recording longer than two hours is refused. Split it and add the parts: Context holds as many sources as you like, and the agent reads all of them.
Older and macro-enabled Office files. An older Word .doc is read directly and needs no
conversion. .xls and .ppt are not: open the file in Excel or PowerPoint and use Save As to
write a .xlsx or .pptx, then upload that. Macro-enabled and template files (.docm, .xlsm,
.pptm, .dotx and the rest) are refused the same way, in Word too.
An HTML document or an SVG diagram is shown rendered. Open one in the file drawer and you see it the way it looks, above the text the agent reads. It is displayed, never executed: nothing in the file runs and it loads nothing from the network, so an export from outside your team is safe to open.
Word (.docx and .doc) and PowerPoint keep their pictures. A screenshot, a diagram or a mockup stays a picture
exactly where the author put it, with a written description beneath it, so the planning agent can
read it and look at it. A picture follows its document: delete or replace the document and its
pictures go with it. Small icons and decorations are left out, and so are the logos on a deck's
slide template.
The pictures are kept as soon as the file lands; their descriptions are written a moment later, so a document you open immediately may show its pictures before their words arrive.
A document keeps up to 50 pictures and describes up to 24 of them. A picture it kept but could not describe says so on the line beneath it, naming the picture and the reason: the workspace is out of usage, no model here can read pictures, the document is past its limit, or that picture could not be read. The picture itself is always kept.
A picture inside a table or a bullet list stays where the author put it, and its description follows the table or the list rather than breaking the row.
An .svg is a Context document, never an image in a spec. An image in a spec is served with none
of the isolation a Context document gets. Archives (.zip and friends) are refused, so upload the
documents inside them.
Files you put in the chat
Paste, drop or attach a file in the plan's conversation and it is saved to the plan's Context in a
folder called attachments, created the first time you use it. It is an ordinary Context document
from then on: the agent reads it, you can open, rename or move it, and it stays after the
conversation ends. The same formats and size limits apply as for any upload.
A file never replaces one already there. A second notes.md lands as notes (2). Removing a file
from the message box before you send deletes it from Context too, unless someone has renamed or
moved it in the meantime.
Code is Context too
A connected repository is Context in every sense. The agent reads it to ground what it writes in the stack and conventions you actually have. It is set up differently, so it has its own page: Connecting a repository.