Documents and artifacts
The Resources page holds the project's longer documents, in two tabs. Documents are files your team uploads, such as specs, PDFs, notes and screenshots, so Dev and your agents can search them and cite them. Artifacts are documents Dev and your agents write for you, such as decision records, plans, guides and runbooks, so the thinking behind the work is kept somewhere everyone can find it.
You'll find it under Knowledge → Resources in the project sidebar. It opens on the Documents tab.
Why upload documents
Upload the material your team already works from: a product spec, an API reference, a design brief, meeting notes, a screenshot of a bug. Once a document is uploaded, Dev can find it from any session in the project and quote it in its answers, and your agents can search it while they work. Nobody has to paste the same spec into every conversation.
Documents belong to one project. Every member of the project can see them.
Upload a document
On the Resources page, press Upload Document and choose one or more files. Each file appears with a progress indicator, then in the list with its name, size and when it was uploaded.
DevSpec accepts these files:
| Kind | File types | Largest file |
|---|---|---|
| Text | .txt, .md, .csv, .json, .xml, .html | 2 MB |
| Code | .ts, .tsx, .js, .jsx, .py, .go, .rs, .java, .rb, .php, .c, .cpp, .h, .cs, .swift, .kt, .sh, .yaml, .yml, .toml, .sql, .graphql, .proto, .css, .scss | 2 MB |
| Word | .docx | 20 MB |
| 20 MB | ||
| Images | .png, .jpg, .jpeg, .gif, .webp | 10 MB |
Older Word files (.doc) aren't accepted: save them as .docx or PDF first.
Files you attach to a message in a session can also become documents: tick Save to project when you attach them, and they appear on this tab. Session attachments have their own size limits (see Sessions).
How DevSpec reads your documents
Text, code and Word files are read as soon as you upload them, and are searchable within moments.
PDFs and images are read in the background after upload, because their text and content have to be extracted first, so they take a little longer to become searchable. You can leave the page while that happens.
Indexing documents for search, including reading PDFs and images, is background work charged to your organization's balance. It appears on Settings → Billing → Transactions as Running your project. See Billing, usage and limits.
If a document can't be read
When DevSpec can't read a document, its row says "We couldn't read this one, so it won't show up in search." Press the retry icon (Try reading it again) to have DevSpec read it again.
If your organization's balance is empty, PDFs and images can't be read and show as unreadable. Add funds, then retry them.
Find, filter and delete documents
On the Documents tab, you can search documents by file name, filter by file type (All files, PDF, Documents, Data, Images or Code), and click tags to narrow the list.
Each document has a Used in AI answers switch. Turn it off when you want to keep an uploaded file on the project without Dev citing it in answers.
To delete a document, press the bin icon (Delete document) on its row and confirm in the dialog. Once deleted, Dev and your agents stop finding it in their searches.
Anyone on the project can see its documents. Contributors and Maintainers can upload documents, change whether a document is used in AI answers, retry a failed read and delete documents. Viewers can see them but can't change them. See Organizations, members and roles.
What artifacts are
An artifact is a standalone document that Dev or an agent writes when a conversation produces something worth keeping on its own: the reasoning behind a decision, a step-by-step runbook, a plan for a piece of work. Each artifact has one of these types:
| Type | For |
|---|---|
| ADR | An architecture decision record: a decision and the reasoning behind it |
| Guide | How to do something |
| Checklist | Steps to tick off |
| Plan | How a piece of work will be done |
| Summary | A recap of a discussion or a piece of work |
| Convention | A written-down standard |
| Runbook | Operational steps, for example for a deploy or an incident |
| Reference | Facts to look up |
| Other | Anything else |
Artifacts are for documents. A short settled fact, such as "we use Postgres row-level security for tenancy", is better kept as a memory.
How artifacts are created
There is no create button on the Artifacts tab. Artifacts are written during the work:
- Dev offers to write one when a session settles something worth a document, and writes it when you agree, or straight away if you ask.
- Your agents can write them too, such as a plan for the work they're doing.
- Artifacts created by automations, and new artifacts proposed by Reviewed Contributors, wait in Review for a Maintainer to accept.
An artifact written in a session links back to it, so you can see the conversation behind it.
Find an artifact
On the Artifacts tab:
- All types narrows the list to one type.
- Live artifacts shows current artifacts; switch it to Archived only to see archived ones.
- Flagged only appears when some artifacts have been flagged, and shows only those. You can narrow it further to Superseded but live or Possibly stale.
- Click tags to show only artifacts with them.
The list loads 30 at a time; press Load more resources for the rest. To find an artifact by what it says, ask Dev.
Open, edit and archive an artifact
Click an artifact to open it. You see the full text, its tags, where it came from (the source session, who wrote it, when it was created and updated, and what replaced it, if anything), and any tasks linked to it.
The buttons along the bottom:
- Copy: copies the text.
- Download: saves it as a Markdown file.
- Edit: change the title, summary, text and tags, then Save. If your change needs approval, use Review changes and send it for acceptance; the current artifact stays in use while it waits.
- Archive: takes it out of the live list. Archived artifacts stay available under Archived only. Unarchive puts one back.
- Delete permanently: appears only on an archived artifact, and removes it for good, with no further confirmation.
To replace an artifact with a new version, ask Dev or your agent. The old one then shows what replaced it.
Connect related knowledge
Ask Dev or your agent to link an artifact with a memory or another artifact, and give a reason. Both show Reads together with, so readers can follow a decision to its full explanation without repeating it.
For two records that describe the same outcome, use duplicate resolution instead: keep the useful detail in one and archive the duplicate. Replacing a document with a new decision is a different choice and follows the decision's approval rules. See Review.
When a document records a decision
A convention or decision record that someone asked for or adopted is protected intent. Work that would undo it needs the appropriate person's OK, shown on the document and in Review. Updating the document does not transfer ownership of its decision.
A convention or decision record an agent created without anyone asking remains background knowledge until someone adopts it. Choose Adopt as my decision when you want to stand behind its reasons and have later work checked against it. See Review.
When an artifact is flagged
DevSpec checks artifacts in the background and flags ones that may need attention. A flagged artifact shows the reason when you open it:
- Superseded but live: a newer artifact replaces it, but this one hasn't been archived. View replacement opens the newer one, and Archive this artifact tidies it away.
- Possibly stale: it may be out of date with your code or the rest of the project.
For Possibly stale, you can answer the flag right there with Still accurate, the same answer as on the Review page, and add a note about why. Discuss opens a session about the artifact instead, and Archive this artifact takes it out of the live list. Implementation-time checks are background work, charged to your balance as Running your project.
Who can change artifacts
Anyone on the project can read, copy and download artifacts, and press Discuss.
Contributors and Maintainers can add artifacts directly; Reviewed Contributors propose them for approval. Viewers can read and discuss them.
Contributors can correct descriptive documents, such as guides and runbooks, and edit their own or other Contributors' knowledge. Editing a Maintainer's decision document waits as a proposed version alongside the current text. Removing someone else's decision needs the appropriate OK; for a Maintainer's decision, that comes from its owner or the project lead.
A Maintainer can rule that a flagged document is Still accurate. Contributors and Reviewed Contributors can propose that ruling, leaving the flag in place until it is accepted. Archiving or restoring a document follows its record-specific permissions. Delete permanently is a Maintainer action.
See Review and Organizations, members and roles.