Specifications Overview

What Are Specifications?

Specifications are structured documents that define the expected behavior of every user-facing feature in Inklings. Each specification describes what the system does — preconditions, step-by-step scenarios, and expected outcomes — without prescribing how it is implemented.

They serve three purposes:

1. Living documentation — Each spec is the authoritative description of a feature’s behavior. When a spec and the code disagree, the spec is updated to reflect the intended behavior, then the code is fixed or the spec is revised.
2. Test authoring guide — Specifications are the source material for the end-to-end test suite (tests/e2e/). Each scenario maps to one or more Playwright test cases.
3. Feature discovery — Browsing the specifications gives a complete picture of what Inklings can do, organized by functional area.

Structure of a Specification

Every specification follows a consistent format:

Section	Purpose
Title & description	Feature name and one-paragraph scope summary
Preconditions	Infrastructure and state required before scenarios run
Scenarios	Numbered behavioral scenarios, each with Steps and Expected results
Test Data	Seed data and fixtures used across scenarios
Notes	Edge cases, design rationale, or known limitations

Scenarios

Each scenario is a self-contained behavioral test case:

### 1. Create a page with a valid title

The simplest create case: a top-level page with a plain ASCII title.

**Steps:**
1. POST `create_page` with title "My First Page"
2. GET `get_page` with the returned slug

**Expected:**
- Page exists with title "My First Page"
- Slug is "my-first-page"
- `created_at` and `updated_at` are set

Scenarios are ordered from simple to complex — the first scenario in each spec covers the happy path, with edge cases and error conditions following.

Organization

Specifications are grouped by functional area:

Area	Scope
Agent	Conversation UI, lifecycle, memory, permissions, presence, skills, tools, MCP server
Editor	Formatting, image blocks, layouts, page attributes, persistence, properties, wiki-links
Navigation	Command palette, first launch, search, sidebar
Workspace	Page CRUD, hierarchy, trash, attachments, tags, type definitions, import, auth, bookmarks, event log

The Smoke Test specification is a standalone infrastructure validation — it confirms the test pipeline itself is working before any feature specs run.

Relationship to Tests

Specifications live in tests/e2e/specs/ alongside the test suite they drive. Each spec file has frontmatter metadata:

---
title: Workspace Page CRUD
area: workspace-pages
priority: P1
persona: any
tags: [core-flow, data-persistence]
seed: seed.spec.ts
---

• area — Maps to a Playwright test partition (port-isolated bridge instance)
• priority — P0 specs are critical-path; P1 are core features; P2 are enhancements
• seed — The seed script that provisions test data before scenarios run

The test suite reads these specs as its source of truth. When a new feature is designed, the specification is written first, then the test implementation follows.

Coverage

The specification suite currently contains 36 specifications covering every shipped feature area. Specifications are added as part of the feature development process — no feature ships without a corresponding spec.