An Artifact in Catalio is a polymorphic note, comment, file attachment, or diagram that you can attach to almost any entity in the system — a Requirement, an Application, an Initiative, a Persona, a Journey, and more. Artifacts are how supporting material and team discussion live alongside the record they relate to, instead of scattered across email threads and chat channels.
Where the entity itself (a Requirement, a Process, a Capability) captures the structured, canonical information, Artifacts capture everything around it: “here’s the context,” “here’s a screenshot,” “here’s what we decided in the hallway,” “here’s a sequence diagram of how this actually flows.”
The Four Kinds of Artifacts
Every Artifact has a kind, which determines what it’s for:
| Kind | Purpose |
|---|---|
| note | Rich-text notes — context, background, or explanations tied to a record |
| attachment | An uploaded file, backed by storage_path and file_metadata |
| comment | Lightweight discussion — a lighter-weight alternative to a full note |
| diagram | A diagram, further classified by diagram_type |
Diagram Artifacts carry an additional diagram_type: architecture, sequence, flowchart, erd, class_diagram, or state_diagram.
Key Fields
| Field | Purpose |
|---|---|
| kind | note, attachment, comment, or diagram |
| diagram_type | Sub-type when kind is diagram (architecture, sequence, flowchart, etc.) |
| title | Optional title for the artifact |
| content | Rich-text body — used by notes and comments |
| storage_path | Where the uploaded file lives — used by attachments |
| file_metadata | Map of file details: content type, size, original filename, and similar |
| status | Lifecycle state: active, archived, or processing |
| pinned | Whether the artifact is pinned to the top of its parent’s artifact list |
| visibility | Access level: private, shared, or internal (default) |
| parent_type / parent_id | The entity this artifact is attached to |
| organization_id | Tenant scope |
Attaching Artifacts to Any Entity
The parent_type / parent_id pair is what makes Artifacts polymorphic — a single Artifact resource can attach to any of these entity types:
- Requirements
- Use Cases
- Test Cases
- Personas
- Components
- Processes
- Policies
- Capabilities
- Initiatives
- Onboarding items
- Metrics
- Journeys
- Journey Steps
- JTBDs
- Applications
- Discovery Sessions
This means the same commenting, note-taking, and file-attachment experience works consistently everywhere in Catalio, rather than each entity type building its own bespoke version.
Visibility
Every Artifact has a visibility level that controls who can see it:
- internal (default) — visible to any member of the organization
- shared — visible only to users or teams with a direct viewer, editor, or owner grant on the artifact
- private — same access rule as
shared; the distinction is about intent, not a separate access mechanism
Organization admins can always see every artifact regardless of visibility. Creating an artifact seeds an owner grant for the creator’s team via SetDefaultOwnership, so the creator’s team retains access even for shared or private artifacts. Visibility is enforced through these direct grants — not through your general OrganizationMember.role (admin/editor/contributor/viewer), which is a separate axis.
This is useful when a note is meant for a specific reviewer rather than the whole team, or when a comment thread should stay scoped to a working group.
Status Lifecycle
An Artifact’s status reflects where it is in its lifecycle:
active (default) — The artifact is live and visible in its parent’s artifact list.
archived — The artifact has been archived, useful for retiring outdated notes or superseded attachments without losing the history. Not deleted — and currently still shown alongside active artifacts in parent artifact lists; there’s no default-view filtering yet.
processing — The artifact is temporarily mid-operation. On an Application’s page, this disables the “re-analyze” action in the UI until the artifact returns to active; the Initiative view has a narrower check that blocks retrying a PRD-enrichment failure while processing, and there’s no domain-level rule enforcing this status for other operations. The current Document Extraction pipeline for Application and Initiative uploads doesn’t set this status on the artifact itself (see that article for what you’ll actually see while a document is being analyzed), so neither guard currently has an effect in practice.
Pinning
Setting pinned: true moves an Artifact to the top of its parent’s artifact list, ahead of everything else, sorted by recency. Use this for the note or attachment your team needs to see first — a pinned decision summary, a canonical architecture diagram, or a comment that resolves an open question.
Attachments and Analysis
Uploading an eligible attachment to an Application can trigger repository comparison and produce Change Proposals directly. Uploading an eligible attachment to an Initiative can trigger PRD enrichment instead; that path only produces Change Proposals after a separate Gap Analysis run. See Document Extraction for how both paths work.
Best Practices
Use the right kind for the job.
A quick clarifying remark belongs in a comment, not a note. Reserve note for content substantial enough to want its own title and formatting.
Pin sparingly.
Pinning is most useful when only one or two artifacts genuinely need to stand out. Pinning everything defeats the purpose.
Set visibility deliberately.
Default internal visibility is right for most team discussion. Reach for private or shared only when a note genuinely shouldn’t be visible to the whole org.
Archive instead of deleting.
If a note or attachment is outdated but might matter for history, archive it rather than deleting it. Deletion (especially for attachments) also removes the underlying stored file.
Give attachments descriptive titles.
“Vendor SOW — signed 2026-03” is more useful later than “Document 1,” both for your team and for anyone searching artifact titles.
Relationships at a Glance
| Related Concept | Relationship |
|---|---|
| Requirements | Requirements (and most other entities) can have attached Artifacts |
| Applications | Application attachments can feed automated document analysis |
| Initiatives | Initiative attachments can feed automated document analysis |
| Change Proposals | Automated analysis of an attachment can generate proposals |
| Document Extraction | Describes the analysis pipeline attachments can trigger |
Next Steps
- Understand Document Extraction — See what happens when an attachment triggers analysis
- Review Change Proposals — Curate anything generated from an attachment
- Add Requirements — A common place to start attaching notes and files
Pro Tip: Artifacts work the same way everywhere in Catalio. Once you’ve used comments on a Requirement, you already know how to use them on an Initiative, a Journey, or a Persona — the experience doesn’t change per entity type.
Support
- Documentation: Continue reading about Change Proposals and Document Extraction
- Email: support@catalio.ai
- Community: Share note-taking and comment workflows with other Catalio users
