Artefae — Capture engagement context and generate delivery artifacts

What is Artefae?

Artefae is a system for capturing Forward Deployed Engineering (FDE) engagements and transforming unstructured conversations into structured knowledge. Instead of manually writing System Design Documents (SDDs), Architecture Decision Records (ADRs), and Requirements & Scope Documents (RSDs), Artefae uses AI to extract this information from your Slack threads, emails, git commits, and meeting notes.

Every decision, system, requirement, and constraint you discuss during an engagement is captured, deduplicated, and organized in a knowledge graph. From this graph, Artefae generates delivery artifacts that are grounded in actual conversations.

Core Concepts

Capture

A capture is a piece of engagement context — a Slack thread, email, meeting notes, or git commit. When you create a capture, Artefae analyzes the content and extracts decisions, systems, requirements, and constraints.

Knowledge Graph

All extracted entities are stored in a knowledge graph that shows relationships between decisions, systems, and requirements. The graph deduplicates entities across captures (e.g., "PostgreSQL database" and "postgres DB" are linked as the same system).

Artifacts

Artifacts are delivery documents generated from the knowledge graph: System Design Documents (SDD), Architecture Decision Records (ADR), Requirements & Scope Documents (RSD), and integration specs. Each artifact is grounded in the actual captures that informed it.

Workspace

A workspace is your team's sandbox. All engagements, captures, extracted entities, and artifacts live within a workspace. Team members can have different roles (Admin, Editor, Viewer) with different permissions.

Your First Engagement

Step 1: Create an Engagement

Go to Dashboard → Engagements and click "+ New Engagement". Give it a name (e.g., "Microservices Migration") and optional description. The engagement becomes a container for all captures and artifacts related to this project.

Step 2: Create Your First Capture

Click "Create Capture" and paste engagement material:

A Slack thread discussing architecture
Meeting notes from a design review
Email thread about requirements
Git commit messages and PRs

Pro tip: Include timestamps and participant names so Artefae can extract stakeholder information.

Step 3: Review Extracted Entities

After Artefae analyzes the capture, you'll see extracted entities:

Decisions — with rationale and owner
Systems — infrastructure, services, platforms
Requirements — functional and non-functional
Constraints — compliance, performance, architectural

Review each extracted entity and provide feedback if anything needs refinement.

Step 4: Add More Captures

As your engagement progresses, create more captures from new Slack threads, emails, and notes. Artefae deduplicates entities automatically — if you mention "PostgreSQL" in capture 1 and "postgres DB" in capture 2, they'll be linked as the same system.

Step 5: Generate Your First Artifact

Go to the engagement and click "Generate Artifacts". Choose the artifact type:

SDD — comprehensive system architecture
ADR — individual architecture decisions
RSD — requirements and scope

Artefae generates the artifact from the knowledge graph, pulling in decisions, systems, requirements, and constraints from all your captures. Review and iterate until it's ready to share with stakeholders.

Understanding the Context Graph

The knowledge graph is where Artefae stores all extracted entities and their relationships. When you view an engagement, you can see:

Nodes

Decision, System, Requirement, Constraint, Stakeholder, Artifact nodes represent the entities extracted from your captures.

Relationships

Edges show how entities relate: "DEPENDS_ON", "AFFECTS", "INTEGRATES_WITH", "RESOLVES", "SUPERSEDES". These relationships power impact analysis and traceability.

Provenance

Every entity has a "SOURCED_FROM" link back to the capture(s) that informed it. This ensures artifacts are always grounded in actual conversations.

Working with the CLI

For teams who prefer command-line tools or need to capture from local files and git repositories, Artefae includes a CLI. It's a thin, authenticated remote client of the Artefae API: you authenticate once with a personal access token, then capture, generate, and export — everything uploads to your workspace and appears in the dashboard. (Self-hosted operators can add --local to drive a local database/Neo4j directly instead.)

Install the CLI

The CLI is a small, pure-Python package that runs the same on macOS and Windows. Only the one-time uv install differs by OS — and uv fetches its own Python, so nothing else is required.

Step 1 — install uv (one-time):

macOS / Linux (Terminal):

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell — reopen the terminal afterwards so PATH updates):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Step 2 — install the CLI (identical on every OS):

uv tool install artefae
# Alternatives (need Python 3.11+ already installed):
#   pipx install artefae
#   pip install artefae      # Windows: py -m pip install artefae

Verify installation:

artefae --version

Authenticate the CLI (one-time setup)

The CLI is a remote client of the Artefae API. Create a personal access token in the web app under Settings → API tokens (the token is shown once — copy it), then register it with the CLI:

artefae auth --api-token <token>

The token is validated against the API and stored in ~/.artefae/config.json for subsequent commands. It's long-lived — revoke or re-mint it anytime from Settings → API tokens. Point at a self-hosted or local deployment with --api-url or the ARTEFAE_API_URL environment variable.

Initialize an Engagement (Cloud Workflow)

Create a local directory linked to a cloud engagement:

mkdir my-engagement
cd my-engagement
artefae init --engagement <engagement-id>

Get the engagement ID from your dashboard (Engagements → view engagement → copy ID). After initialization, you'll have a .artefae/ directory linked to your workspace.

Capture from Local Files and Directories

Create captures from individual files or recursively capture entire directories:

# Capture from a single file
artefae capture --file architecture.md

# Capture all files in a directory (recursively)
artefae capture --folder ./engagement-docs

# Capture recent git activity (default window: 1 week)
artefae capture --git --since "2 weeks ago"

The CLI uploads the sources to the API, which extracts entities with Claude and updates the knowledge graph server-side. Self-hosted operators can add --local to write straight to a local database/Neo4j instead.

Generate and export artifacts

Once you've captured enough context, generate deliverables and export them from the CLI:

# Generate an artifact (sdd | adrs | integration | rsd)
artefae generate --artifact sdd -o SDD.md

# Export the latest artifact (markdown | pdf | docx | html)
artefae export --format pdf -o SDD.pdf

Run artefae status anytime to confirm your identity and the workspaces your token can reach.

Automatic Extraction

When you run `artefae capture`, the CLI:

Gathers and validates the sources locally
Uploads them to your workspace over the API
Triggers server-side extraction (decisions, systems, requirements, and more) into the knowledge graph

$ artefae capture --folder ./docs/

Captured 5 record(s), 2,450 words total.
  uploaded 5 new capture(s) to engagement abc123 (5 in database, 0 in S3)
  Extraction runs server-side.

Go to your dashboard to review the extracted entities and generate artifacts (SDD, ADR, RSD) — or generate them from the CLI with artefae generate.

Hybrid Workflow (CLI + Dashboard)

The recommended approach combines both:

CLI: Authenticate once with artefae auth --api-token
CLI: Capture from local files, git history, and markdown notes
CLI: Captures upload to your workspace and extract server-side
Dashboard: Review extracted entities, generate artifacts, collaborate with team
CLI: Iterate locally, capturing new sources as the engagement evolves

End-to-End CLI Workflow

The full flow from an empty terminal to an exported deliverable. The CLI drives everything over the API, so captures and artifacts show up in your dashboard automatically.

Step 1: Authenticate (one-time setup)

artefae auth --api-token <token>

Create the token in the web app under Settings → API tokens (shown once). The CLI validates it and stores it in ~/.artefae/config.json. It's long-lived; revoke it anytime from the web app.

Step 2: Initialize Your Engagement Locally

artefae init --engagement abc123def456

Your engagement ID comes from the dashboard (or artefae engagement list). This creates a local .artefae/ directory bound to that engagement, so later commands don't need the id.

Step 3: Create Captures Locally

artefae capture --file ./notes.md

The CLI uploads the file to your workspace; extraction runs server-side and the capture appears in your dashboard.

Step 4: Generate & export from the CLI

Generate deliverables from the knowledge graph and download them in any format:

artefae generate --artifact sdd -o SDD.md
artefae export --format pdf -o SDD.pdf

SDD generation is gap-gated — if a critical gap remains (e.g. a decision with no rationale), the CLI lists exactly what to fix. ADR/integration/RSD are not gap-gated.

Step 5: Review & collaborate in the dashboard

Go to your engagement in the dashboard. You'll see:

All captures uploaded from the CLI
Extracted entities (decisions, systems, requirements)
Generated artifacts (SDD, ADR, RSD) and team collaboration

Key Benefits of the CLI Workflow

Local sources: Capture straight from files, folders, and git history
Automatic Extraction: Claude extracts entities server-side after each upload
Team Collaboration: Uploaded captures appear in your team's dashboard
Simple auth: One long-lived personal access token, revocable anytime
Single Source of Truth: Dashboard becomes the central record

Best Practices for Early Success

✓ Capture early and often

Don't wait until the end of an engagement. Create captures as decisions are made, requirements are discussed, and systems are designed. This gives you a complete picture of how the engagement evolved.

✓ Include context and names

When capturing Slack threads or emails, include timestamps and participant names. Artefae uses this to extract stakeholder information and ownership.

✓ Review extracted entities

After Artefae extracts entities, spend a few minutes reviewing them. Correct any misclassifications or add missing context. This training improves the quality of future captures.

✓ Use templates for consistency

If your team runs similar engagements, create a template to standardize capture schemas and artifact generation. This ensures consistency across projects.

✓ Invite your team

Collaboration makes engagements better. Invite teammates as Editors to help review captures and artifacts. Different perspectives catch gaps and improve quality.

Next Steps

You're ready to start! Here's what to do next:

Create your first engagement in the dashboard
Add a capture from a recent meeting, Slack thread, or email
Review the extracted entities and provide feedback
Generate your first SDD or ADR from the knowledge graph
Iterate with your team to refine the artifact

Common Questions

Q: How long does capture analysis take?

A: Most captures are analyzed in 5-30 seconds. Larger captures (10KB+) may take up to a minute.

Q: Can I edit extracted entities?

A: Yes! Review the extracted entities and edit them if needed. You can also add new entities manually if Artefae missed something.

Q: What formats can I capture?

A: Plain text (Slack threads, emails, meeting notes, git commits, markdown). Copy/paste from any source.

Q: Can I regenerate artifacts?

A: Yes! After adding more captures or editing entities, regenerate any artifact to get an updated version grounded in the latest knowledge.

Q: Do I have to use the dashboard?

A: No! Once authenticated, the CLI can create engagements, capture from files/git, and generate and export artifacts entirely from the terminal. The dashboard shows the same data for review and team collaboration. See "Working with the CLI" above for details.

Q: Can I capture from git history?

A: Yes! The CLI captures recent git activity directly: artefae capture --git --since "2 weeks ago". This pulls in commit messages from your local repository so architectural decisions in your history get extracted.

Q: Does the CLI upload captures to the cloud?

A: Yes! Run artefae auth --api-token <token> once (one-time setup). After that, artefae capture uploads to your workspace and extraction runs on the backend, so captures appear in your dashboard. Self-hosted operators can add --local to write to a local database/Neo4j instead. See the "End-to-End CLI Workflow" section above for details.

Getting Started with Artefae