Documents

A document is a workspace-wide record that you attach where it is useful. The customer-complaint PDF that started the conversation, the customer's CSV format spec, the screenshot of the failing export, the zip file with the customer fixture set. They all live in the same library, and the team attaches each one to whichever initiative, plan, or bug it belongs with. A single document can be attached in several places at once; the library is the source of truth, and the attachments are typed links from the library to the work.

What makes this matter day to day is the agent. At the start of every chat or flow, the platform materializes every attached document into the sandbox under a stable path layout, so the agent reads them as part of the work context. The customer-complaint PDF is one of the first things the agent sees when it opens a session on the CSV Export initiative; the format spec is in the sandbox the moment a flow runs against the CSV server endpoint implementation plan. The agent never has to ask what is the customer expecting?, because the customer's own words are sitting in the workspace alongside the spec the team is shipping.

If you are coming from a hand-rolled mix of Google Drive folders, Slack pinned messages, and Confluence pages, this is the part of the product that ends the we have it somewhere problem. If you are coming from a dedicated wiki, this is closer to a Notion-style library than to a Confluence space, with the important difference that the agent reads from it.

How a document sits in the work model

A document is stored in the workspace-wide library. Attachments are typed links from the document to an initiative, a plan, or a bug. Cloud providers (Google Drive and OneDrive) source new documents into the library. The sandbox is where attached documents land at the start of every chat or flow.

How it looks in practice

Continuing the worked example.

Sarah's CSV Export initiative carries four attached documents, each living in a different place inside the work and each driving a different part of the team's thinking.

Now look at how the documents connect.

Upward through the propagation cascade. When a document is attached to a plan, the platform also attaches it to the plan's parent initiative. When a document is attached to a bug, the platform also attaches it to the parent plan. The propagation runs one level at a time and is one-directional: the propagated attachment carries a tag indicating it came from a sub-entity, so the parent knows where the document originated. The verifier who attaches the Failing-export screenshot.png to the bug sees the screenshot also appear under the parent plan, without anyone having to re-attach it; if the team wants the screenshot to also surface at the initiative level, they attach it again from there (a one-click move from the same drawer).

This is what makes a chat session on the initiative actually rich. The agent opening a session on the initiative sees every document attached at the initiative level (including the customer complaint, the format spec by way of the spec plan, and the fixture set by way of the verification plan) materialized into the sandbox at the same path layout it can rely on.

Across the library. Every document is a workspace record. The Customer complaint email.pdf attached at the initiative is the same record that would appear in any other attachment of it; if a year later the team starts a follow-up initiative, they can attach the same record from the library without re-uploading. The library is the source of truth.

Into the sandbox. At the start of a chat on the CSV Export initiative, the agent's sandbox is populated with all four documents. Text files (the CSV format spec.md) arrive as-is. Binary files (the PDF, the PNG, the ZIP) arrive as markdown stubs wrapping a base64-encoded payload, so the agent always reads markdown first and can decode the binary content when needed.

Rollups at a glance. On the initiative's Documents tab, the team sees four attachments: one directly attached, three propagated up from sub-entities (rendered with a small via Plan or via Bug badge so the lineage is visible).

How the agent uses attached documents in a chat

This is the moment the rest of the surface earns its keep. Sarah opens Continue in Chat on the CSV Export initiative. The chat opens with the agent's working context already populated by the customer-complaint PDF, the CSV format spec, the failing-export screenshot, and the customer fixture set. Sarah's first message is what does the customer actually want? The agent does not ask her to paste anything; it reads from the PDF and quotes the customer's specific complaint about timezone handling. The team has not done any extra work to make this happen. They attached the documents once, and every chat session for the initiative now opens with the right context in the room.

The shape of this matters because the alternative is the silent default in most agentic tools: the team pastes the customer's email into the chat window every time someone opens a new session, or worse, the agent answers from training-data assumptions about what customers usually want. Both are bad. The first wastes the team's time; the second produces work that does not match the customer's actual problem. The library-plus-materialization model makes the documents the starting context rather than the thing someone has to bring to the conversation.

The customer-complaint PDF is the canonical example to lead with on this. The hardest part of any agent-driven work is keeping the agent grounded in the actual customer voice; the document attachment is the simplest, most direct way to do that. A team that learns to attach the customer artefact at the initiative level (once, at the start) gets every chat session for that initiative grounded in the right voice for free, including the sessions opened weeks later by a different engineer on the team.

The shape this displaces is the silent default in most agentic tools: the team pastes context into the chat window every time someone opens a new session. The pasted-prompt workflow is fragile (someone forgets), duplicative (the same paste lands in twenty sessions), and unauditable (no one can answer which version of the spec was the engineer working against?). The library-plus-materialization model is the structural fix; the team attaches once and every session for the rest of the initiative's life opens with the right context in the room.

A worked example of the propagation cascade

Wednesday morning. Priya, the verifier on the CSV Export work, is exercising the CSV format verification plan against the staging build. The Export across timezone boundaries test case fails: the exported CSV shows times in UTC when the customer expected the local timezone. Priya takes a screenshot of the failing output and clicks File Bug on the test case row.

The bug-create drawer opens pre-populated with the test case relation. Priya drags the screenshot onto the bug's Documents tab. The platform writes three things in one round-trip: the screenshot is created as a document in the library (owner Priya, visibility Tenant), the screenshot is attached to the bug, and the screenshot is propagated to the bug's parent plan (the CSV server endpoint implementation plan). Priya saves the bug. The work she did is one upload.

Thursday morning. Tom, the implementation engineer working the CSV server endpoint plan, opens his plan to start the day. The Documents tab on his plan now shows a screenshot he never attached, with a via Bug propagation badge. He clicks through to read it before opening Continue in Chat; the chat session opens with the screenshot already materialized in the sandbox, so the agent's first message references the specific export output the customer saw rather than asking what was wrong.

Three days in, Sarah opens the initiative for a weekly check-in. She sees the screenshot at the plan level with the via Bug badge, decides it deserves visibility at the initiative level too, and attaches it from the initiative's Documents tab in one click. The library now has the screenshot referenced from the initiative, the plan, and the bug; the team's library reflects where the screenshot is useful without anyone managing the references by hand.

When you upload one

The fastest path is from the place the document belongs to. Open the initiative, plan, or bug; click into its Documents tab; click Add Document. A drawer opens with two paths.

Upload from your machine

Drag a file onto the drop zone or click to pick. The upload supports files up to 50 MB. The platform asks for a name (defaulting to the filename without the extension), an optional description, and an optional visibility (Private to you, or Tenant to share with the workspace). The upload writes the file to per-tenant blob storage; the document is created in the library and the attachment is created in one operation.

Pull from Google Drive or OneDrive

If you have connected your account through the platform's OAuth flow, the drawer's Cloud tab lets you search and pick a file from the connected provider. The platform fetches the file's metadata and content at pick time, imports them into the library as a new document, and creates the attachment, all in one round-trip.

The first time you click into the Cloud tab on a new workspace, the drawer shows a Connect Google Drive or Connect OneDrive button instead. The button opens an OAuth popup; you consent to read-only access to your provider files, and the platform stores the connection for future picks. The flow uses PKCE so the authorization code exchange does not require a stored client secret; tokens are kept per-user in an encrypted session store on the platform, and the OAuth state itself expires after ten minutes if the team member never finishes the consent flow.

Attach a document already in the library

The Cloud tab also doubles as the library search. Type to filter every document in the workspace by name, source, or owner; click a document to attach it. This is the common path for documents that show up across multiple pieces of work; the library is the source of truth and the attachment is a typed link rather than a copy.

The library

The Document Library at /planning/documents is the workspace-wide view of every document. It runs on the shared data grid, so every standard affordance is available: column filters, the filter panel, inline editing for the document's metadata, bulk operations, and shareable URL views.

The default columns are source icon, name, source type chip, size, owner, attachment count, and updated timestamp. The attachment count surfaces how many places this document is attached; a high count usually means the document is foundational and worth indexing.

Filters and search

The toolbar's search box filters on the document name and description. The filter panel adds source (uploaded / Google Drive / OneDrive / external), visibility (private / tenant), and storage type (blob / reference). A reference document is one whose content the platform did not store directly (a pasted URL to an external page); it shows up in the library with a Reference badge and renders in the sandbox as a markdown stub linking to the source.

The trash view

A toggle in the toolbar switches the library to deleted-only. Each row in the trash view shows a Deleted badge; clicking through opens the document's detail drawer where the Restore action lives. Restore puts the document back at its previous state with its attachments intact. The drawer also offers the permanent delete action; this is the irreversible cleanup path that removes the blob, every stored version, every attachment link, and the record itself in one operation.

The trash view is meant for the team's quarterly cleanup pass, not for everyday work. Most documents that leave the active set stay in the trash for the rest of the quarter (in case the team needs them back) and get permanently deleted in a batched review at the end. The audit log records every soft-delete, restore, and permanent delete with the actor and the timestamp; an accidental delete is recoverable as long as the permanent action has not been taken.

When to attach vs when to link in a comment

A boundary question that comes up most often when a team first starts using documents seriously. The answer is usually clear once you ask does the agent need to read this?

Attach when the document is part of the work's context: the customer spec the team is building against, the failing-export screenshot the verifier saw, the fixture set the verification plan exercises, the design mock the engineer is implementing. Attached documents materialize into the sandbox, so the agent reads them as part of every chat session and flow run; the team's reviewers read them without leaving the page; the propagation cascade carries them up to the parent entity for the cross-team read. The attachment is a durable association.

Link in a comment when the document is incidental: the Slack thread where the customer first raised the complaint, the meeting notes from the kickoff conversation, the Confluence page that describes the broader product strategy. Links in comments are conversational; they reach into other systems, they do not materialize into the sandbox, they do not propagate. The link is a pointer to where the conversation happened, not a piece of the working context.

The rough rule: if the agent should read the content, attach. If the content is for a human to glance at and click through, link in a comment.

Sharing documents across the team

The visibility model is two values per document: Private (the owner only) or Tenant (every workspace member with documents.read). The choice is on the document itself, not on the attachment, and the reason is worth understanding.

A document is a record; an attachment is a typed link. Flipping a document from Private to Tenant shares it everywhere it is attached, in one move. Conversely, attaching a Tenant document to a private project does not somehow privatize the document; the document was already a workspace record and stays one. The team controls sharing at the document level because that is where ownership actually lives.

What should I set this to?

The decision is usually quick. Private is the right setting when the document is part of your gathering: a draft you have not yet shown anyone, a screenshot from a debug session you do not yet know how to interpret, a competitor PDF you are reading for context. Tenant is the right setting when the document is part of the work: a customer artefact the team will reference, a spec the implementer is building against, a screenshot a verifier captured. The boundary question is do you want a teammate who opens the work to see this without asking?

A document set to Tenant should not be reverted to Private through the library; the workflow is meant to be one-directional, because un-sharing a document the team has already grounded against creates more confusion than it solves. To restrict access to a Tenant-shared document later, soft-delete it through the trash flow and re-upload as Private if a fresh copy is genuinely needed. The discipline matters: documents are records, not drafts.

Ownership, soft-delete, and quarterly cleanup

The owner field is the person who imported the document, recorded once and stable. Anyone with documents.manage can soft-delete a Tenant document; the trash view is shared. The audit log records who deleted what, who restored what, who flipped visibility, with the actor and the timestamp. The team's discipline is what keeps the shared trash from becoming a free-for-all; the platform records the discipline so a quarterly review can read it.

Documents that move with the team

The propagation cascade is documented above as a mechanism. It is worth one more look as a productivity feature, because the canonical shape is something the team feels as friction-removed work, not as a system behavior.

A verifier files a bug while exercising a test case. The bug needs a screenshot; the verifier drags it onto the bug's Documents tab. The platform attaches the screenshot to the bug, and propagates an attachment up to the parent plan, so the engineer working the fix sees the screenshot in their plan's Documents tab the moment they open it the next morning. The verifier did one upload; the screenshot is in two places where it is useful.

What this removes is the team's invented convention for where do we put the screenshot? Without propagation, every team builds a different answer (attach to the bug? to the plan? to both? to the initiative for visibility?), and the conventions break the first time someone forgets the rule. The propagation cascade picks the answer for the team and then carries the document everywhere it is useful, automatically.

Organizing the library at scale

A workspace with a year of attached documents accumulates real volume. The library is built for this.

Tags are the at-scale labeling. A document carries a comma-separated list of tags, editable inline from the detail drawer. A team running for two years has settled on twenty to forty active tags; the library's tag filter is the everyday read.

Search is the at-scale read. The library's search runs across name and description, with the filter panel narrowing on source, visibility, and storage type for further precision. A team that has been gathering documents for a year and starts a follow-up initiative reaches for the search box first, not the tag panel.

The attachment count is the relevance signal. A document attached in twenty places is foundational to the team's work; a document attached in one place is incidental. The library's attachment-count column is sortable and the count is server-maintained on every attach and detach; a team curating its document set at quarter-end starts at the top of the sort.

When the team's library hits 500 documents

A workspace running for two or three years accumulates real volume; five hundred to a few thousand documents is typical for a team that has been treating the library seriously. At that scale, three patterns hold up.

The top twenty documents by attachment count are the team's institutional knowledge. The customer-facing spec the team has been refining, the customer fixture set every verification plan still uses, the architecture diagram a year of plans have grounded against. The library's sort surfaces them automatically; the team's quarterly read on them confirms they are still the right versions.

The stale-document review becomes quarterly work. Documents not touched in two quarters get a review pass at quarter-end. The library's Updated column sort is the natural starting list; an owner can defend a long-untouched document as a frozen record worth keeping, or soft-delete it through the trash flow if no one defends it.

The library does not ship a folder hierarchy on purpose. Folders impose a single classification on every document; tags let the same document live under three or four overlapping reads. A team that has run on tags for a year does not want to go back to folders, and a team that arrives at the platform from a folder-based system finds the tag model feels strange for two weeks and right thereafter.

Attachments and auto-propagation

Attachments are typed links from a document to an entity (an initiative, a plan, or a bug). The model is library-first: a document exists in the library, and attachments connect it to where it is useful. One document can be attached to many entities; an entity's Documents tab shows the list.

The propagation cascade

When you attach a document to a plan, the platform also attaches it to the parent initiative. When you attach a document to a bug, the platform also attaches it to the parent plan. The propagation runs one level at a time. The propagated attachment carries a tag indicating it came from a sub-entity, so the parent's Documents tab shows at a glance which attachments were directly added and which were inherited from the work underneath.

The propagation runs in one direction only. Removing a document from the initiative does not remove it from the plan or the bug; removing it from the plan does not remove it from the initiative. Each layer has its own attachment record, and the team can manage them independently.

This shape pays off for the agent. A chat session running on the initiative sees every attachment at the initiative level, which includes documents that propagated up from sub-entities. The agent does not need to climb the tree on its own; the propagation made the documents reachable from one place, with the lineage badge ("via Plan", "via Bug") visible so a reader knows where the document was originally attached.

Detaching

A document detached from one entity stays attached to the others. The library record is unaffected. The detach control is on each attachment row in the entity's Documents tab; clicking it asks for confirmation and then drops the link.

Cloud providers

The platform supports two cloud document providers today: Google Drive and OneDrive.

Google Drive

The first time you connect, the platform opens a Google OAuth popup that requests read-only access to your Drive (drive.readonly scope). The popup uses PKCE so the authorization code exchange does not require a long-lived client secret on the device. You consent, the popup closes, and the Cloud tab on the document drawer is now wired to your Drive.

What it looks like the tenth time: search, pick, import. The picker reads your Drive listing on demand; picking a file fetches its metadata (name, MIME type, size) and content at pick time and stores the content in tenant blob storage as the document's current version. A small PDF lands in under a second; a large CSV or a multi-MB image takes a moment longer.

A worked example: the customer-success team keeps a shared Drive folder with one PDF per customer complaint. Sarah's Analytics team pulls the CSV Export complaint into the initiative; the document is now in the workspace's library as a tenant-visible record with a clean version history. The customer-success team's Drive is unchanged; the workspace has its own copy and can continue working from it without affecting the source.

The Drive connection is per-user. Each workspace member who wants to import from Drive connects their own account; the platform does not impersonate a shared service account. Tokens live in a per-user session store, refresh automatically on the next use, and expire if you revoke access from your Google account settings.

OneDrive

The OneDrive provider works the same way. The OAuth flow requests Files.Read.All offline_access openid scope, supports multi-tenant Microsoft accounts (work, school, or personal), and uses PKCE. The first connection opens the Microsoft consent popup; subsequent picks read the OneDrive listing on demand.

A worked example: the company's design team keeps the customer-facing spec documents in OneDrive. The engineering team's plan author pulls the design spec for the Reporting page into the CSV Export on the Reporting Page initiative when implementation starts; the document lands in the library, attached to the spec plan, and propagates up to the initiative on attach. A chat session opened on the initiative the next day reads the design spec as part of its working context, without the engineer pasting anything.

Disconnecting cleanly

A user who leaves the team, rotates their Google account, or moves the workspace's source of truth off a connected provider needs a clean way to cut the connection. The model is straightforward, because the connection was only ever your own read-only grant. You revoke Disco Parrot's access from your Google or Microsoft account settings, the same place you manage every app you have authorized, and the connection stops working on the next use. The documents already imported through it stay in the workspace library as workspace records; they no longer have a live link back to the provider, but the cached content is intact and every attachment continues to work.

A team rotating providers (most often: a team migrating from a personal Google account to a shared OneDrive at company adoption) revokes the personal connection, connects the shared one, and re-imports the documents that still need a live source link. The connection is never migrated silently; the team makes the call explicitly, because a silent migration would mean some documents track a source the team no longer trusts.

Versioning

A document carries its own version history. Every content upload writes a new version row with a version number, a content hash, the importer's user ID, and an imported-at timestamp; the document's current version is the one that materializes into sandboxes. Older versions stay in storage as a real record of the file's history.

Document versioning records file revisions; the entity-versioning system that snapshots initiatives, plans, skills, and agent instructions records record edits. The two are complementary and non-destructive.

A document uploaded once stays at v1 for its lifetime. A document that gets a fresh upload (a customer's updated format spec, a re-imported design mock) gains a v2; the v1 stays readable through the version history. The team is not expected to clean up versions; the history is meant to be read, not maintained.

Replacing a document

When the content of a document changes, the team has two paths.

Re-upload from the detail drawer. Drop a new file onto the document's detail drawer. The new file becomes the current version; the previous version stays in the history. Use this when the new content lives on your machine. The new version inherits the document's existing attachments and visibility, so the change shows up everywhere the document is attached without re-attaching.

Re-import from the connected provider. For a cloud-sourced document, pick a fresh copy from the same provider through the document drawer. The platform compares the new content against the current version, and when it has changed, stores it as the next version and updates the current pointer. Use this when the source of truth is in the cloud provider and the team wants the workspace copy to track the source.

The audit log records every replacement with the actor and the timestamp. A team that re-uploads the customer's format spec four times across the quarter can read the history as a real record of how the spec evolved, with each version still readable in place.

Replacing a customer-supplied document mid-quarter

A customer sends an updated format spec in week six of the quarter. The first question on the team is not how do I upload it (that part is mechanical); the first question is what happens to the work that was already grounded in the v1 spec? The answer is: nothing automatic, by design.

Re-upload the new spec from the document's detail drawer. The v2 lands as the current version; every place the document is attached now reads the v2 in the next sandbox materialization (the next chat session, the next flow run). The team's implementation plan that was grounded in the v1 spec keeps its existing version-history snapshots; the verifier reading the CSV format verification plan a week later sees the v2 spec in the materialized sandbox alongside the v1-baseline test cases.

The platform does not automatically reset the test cases or alert the engineers. The team's responsibility at that point is real product judgment: is the v2 a clarification (the existing work still applies), a breaking change (the test cases need new fixtures), or a new feature (a fresh plan is the right shape)? The audit log on the document records the re-upload with the actor and the timestamp; the version history makes the v1 still readable so the team can read what was there before; the team makes the call from there. The platform's job is to keep the trail honest; the call about what the trail means is the team's.

Sandbox materialization

This is the part of documents that makes them more than file storage. At the start of every chat session and every flow run on an initiative, the platform walks the initiative and its plans, gathers every attached document, and writes the documents into the sandbox under a stable path layout.

The agent reads the materialized documents as part of its working context. A chat about what does the customer want from the export? opens with the customer's complaint email and the format spec already in the sandbox; the agent grounds its answer in those documents instead of asking the team to paste them in.

Why the path layout is stable

The path layout is the same on every run by design. A flow author writing a verification flow knows exactly where the fixture set will be (/workspace/initiatives/{slug}/plans/{plan-slug}/attachments/customer-fixture-set.zip); the flow can unpack it and run the format check without anyone re-parameterizing the path every time. If the path changed per-run, every flow that reads a fixture file would have to look in a search-style way instead of a direct way, and the team would lose the productivity that the materialization is meant to deliver. The stability is the contract the flow can rely on.

What does not get materialized

Soft-deleted documents are skipped at materialization. The sandbox sees only the active attachments at chat-start time; a document that has been moved to the trash drops out of the sandbox on the next session, even if the attachment record is still on the entity. Restoring the document brings it back into materialization the next time a chat opens.

Materialization runs as a platform operation on behalf of the initiative; it gathers the attachments scoped to the initiative and its plans without an additional per-actor visibility filter. This is consistent with the access model on the Documents tab itself: a member who can open the initiative can read its attachments through the tab, and the sandbox inherits the same view. The right place to manage who sees what is the document's visibility setting (Private vs Tenant) at the library level, not the materialization layer.

Materialization is read-only

The post-step sweep that lands the agent's edits back to the platform does not write to attached documents. If the agent generates an updated format spec during a chat, the spec shows up as a fresh document in the library that the team can review before attaching, rather than as an overwrite of the customer's original. This is what keeps the customer's source documents trustworthy; the team's library is a record of what the customer gave us, not what we worked on top of it.

Documents vs Documentation

A naming knot worth clearing up.

The Documents tab on an initiative, plan, or bug is the per-entity attachments view described throughout this page. It shows the documents attached to that entity (counting propagation), with controls to attach, detach, and inspect.

The Documentation tab on an initiative is a different surface entirely. It renders the repository wiki for the project's linked repository, scoped to the initiative. The repository wiki is a structured documentation set the platform keeps fresh through the repository documentation health flow; it lives in your Git repository, not in the documents library, and it shows up as a rendered wiki rather than a list of attachments.

The two tabs answer different questions. What did the customer give us? opens the Documents tab. What does the codebase already know about how this part of the product works? opens the Documentation tab. Some initiatives use both heavily; some use neither. Knowing which is which is the part most teams learn in week one.

Permissions

Three scopes govern documents.

• documents.read lets a person view the library, search it, view individual documents, download them, and see attachments on entities.
• documents.manage lets a person upload, edit, attach, detach, delete, and restore documents.
• doc-providers.read lets a person initiate the cloud-provider OAuth flow and browse files in a connected provider; doc-providers.import lets them bring a picked file into the library. The full connection model is on the document providers page.

Visibility on a document is binary: private (the owner only) or tenant (every workspace member with documents.read). The visibility is a property of the document record itself, not of the attachment; a tenant-visible document attached to a private project is still readable through the library by anyone with documents.read. This is the platform's general posture: documents are workspace-shared records by default, and the team controls sharing at the document level.

Cross-links