Documents vs. Artifacts
Use artifacts for work you create and edit inside a project, and documents for read-only files in Knowledge that chat searches for context. They have different permissions and are searched differently.
At a glance
| Artifacts | Documents | |
|---|---|---|
| What they are | AI-generated outputs you create and iterate on | Files uploaded from external sources or saved from artifacts |
| Where they live | Your project, organized by category and artifact type | Knowledge, organized by data source and collections |
| Who creates them | You (via chat, workflows, or API) | Uploaded manually, synced from data sources, or saved from artifacts |
| Editable? | Yes. Edit directly, or ask in chat to update it | Content can't be edited. Collections and groups can |
| Permission model | The project's access, plus the category's groups if it's in a category | The document's own groups, plus its data source's groups |
| How they're searched | Full-text search on name and content | Search by meaning and by exact words |
Artifacts
Artifacts are the outputs of your work in Revelry Ai. A PRD, a user story, a technical spec, or any other content it creates for you is an artifact.
Key characteristics:
- Created in chat (by the artifact tools, or by saving one message), in Workflows, or through the API
- Optionally classified by an Artifact Type and filed under a Category, set separately
- Editable directly, or updated by asking in chat
- Searchable by name and content within their project, ranked by relevance
- Visible to people with access to the project, narrowed to the category's groups when the artifact is in a category
Learn more: Artifacts Overview
Documents
Documents are files in Knowledge: uploaded by hand, synced from data sources such as GitHub, or saved from artifacts. They're what Revelry Ai draws on during conversations.
Key characteristics:
- Come from external sources or are explicitly saved from artifacts
- Live in Knowledge, optionally organized into collections
- Their content can't be edited, though you can change a document's collections and groups
- Searchable by meaning and by exact words
- Visible to people in the document's own groups or its data source's groups
Learn more: Documents
Why they're separate
Artifacts and documents have different permission models and lifecycles. Keeping them separate means:
- Permissions stay clear. Artifact access comes from the project and its categories. Document access comes from the document's groups and its data source's groups.
- Each keeps its own lifecycle. Artifacts are work you keep editing. Documents are reference material from their sources.
- You choose what goes into Knowledge, since not everything you create should be searchable by everyone.
The bridge: saving artifacts to Knowledge
When you want an artifact to be searchable in Knowledge, you explicitly save it to Knowledge. This creates a linked document that mirrors the artifact content.
When you save to Knowledge:
- You choose which groups can see the document, and you can add it to collections in the same step
- A document is created that stays in sync with the artifact
- Knowledge Search in chat can find the document
- People in those groups can find it too
This is intentionally opt-in. You decide what knowledge enters the shared pool and who can access it.
Learn more: Saving to Knowledge
Categories vs. collections
Categories and collections are both ways to organize content, but they operate on different sides of the artifact/document boundary.
Categories (for artifacts)
Categories organize artifacts:
- A category is a folder for artifacts, such as "Product" or "Engineering"
- Categories form a tree, with subcategories up to three levels deep
- Filing an artifact in a category is optional, so an artifact can stay uncategorized
- An artifact can also have an artifact type describing its format and purpose, set separately from its category
- A category's groups narrow who can see the artifacts in it
Collections (for documents)
Collections organize documents in Knowledge, and they can overlap:
- A collection can hold many documents and data sources
- A document can belong to several collections, or none
- A data source can be added to several collections
- A collection narrows what Knowledge Search covers in a chat
The same document can sit in a "Q1 Planning" collection and an "Engineering Reference" collection at once.
Why can't artifacts go in collections?
Artifacts live outside Knowledge, and collections hold Knowledge documents. To put an artifact's content in a collection, save it to Knowledge as a document and pick the collections in the same step.
Saving is also where you choose who can see the document version. An artifact's access comes from its project and category, which doesn't carry over to Knowledge, so the document gets its own groups when you save it.
How search works
Revelry Ai searches artifacts and documents in different ways, and it works through results in rounds: search, scan the results, refine, and search again.
Artifact search
Artifact search matches words in artifact names and content within the current project. Results can be sorted by relevance, so the closest matches come first. It always searches the current content, so there's no sync delay.
Document search
Knowledge Search finds documents three ways:
- By meaning, so related content turns up even when the exact words don't match
- By exact words or phrases within each document's sections
- By document name, type, or format
For a large document, it searches section by section and reads only the parts that match.
Searching in rounds
Knowledge Search runs several searches in rounds, refining each one. Your first question doesn't need to be perfect, since each round narrows the search.
Common patterns
"I want this artifact searchable outside its project"
Chat in the same project can already find it. Save it to Knowledge to make a document that Knowledge Search finds for people in the groups you choose.
"I want to keep this artifact private while I work on it"
Don't save it to Knowledge. It stays in your project, visible to people with access to the project and its category, and Knowledge Search won't return it.
"I uploaded a document and want to create content from it"
Ask about it in chat with Knowledge on. Knowledge Search finds it, and the artifact tools create artifacts from what it finds.
Next steps
- Artifacts overview: managing your artifacts
- Documents: managing your documents
- Saving to Knowledge: turning an artifact into a document
- Tools in chat: the tools chat uses to search both