Knowledge base

The knowledge base is the set of harness docs Flow installs into your project. In this guide, you will learn:

• What the knowledge base is and why Flow curates it
• Which packages and topics it covers
• How an agent uses the knowledge base while it works
• How the docs are written

Overview

The knowledge base is a collection of AdonisJS reference docs that Flow copies into your project's .flow/docs/ directory. Each doc covers one topic, such as routing, controllers, Lucid models, or Vine validators, and is matched to the major version of the package your application actually depends on.

These docs are the reference-knowledge part of the harness described in Why a harness. An agent that reads them stops guessing AdonisJS APIs from training data and starts working from a current, project-specific source.

Why Flow curates the docs

Two reasonable questions come up here: why not let the agent use its own knowledge, and why not just point it at the full AdonisJS documentation site.

The first is answered in Why a harness. An agent's training data blends framework versions and cannot be trusted for version-specific code.

The second is subtler. A framework's full documentation is written to teach a human every feature. An agent does not need that. It needs the one recommended way to do a task, the patterns to avoid, and confirmation of which API names are real so it does not invent ones that are not. A harness doc is a narrow working reference, not a course. It is deliberately smaller than the upstream documentation, because every irrelevant paragraph is context the agent has to wade through to reach the part that matters.

There is a structural reason too. Flow's workflow skills never hardcode framework facts. An API name, a config key, a file path: all of it lives in the knowledge base, and the skills read it at the moment they need it. Keeping framework knowledge in one place means a framework upgrade is a docs update, not a hunt through every skill for a stale assumption.

What the knowledge base covers

The installer copies docs only for the supported packages it finds in your package.json, so your .flow/docs/ directory reflects your actual stack. Across the supported packages, the knowledge base covers:

• The framework core (@adonisjs/core): routing, HTTP context, the request, controllers, middleware, responses, exception handling, transformers, the design system, and testing.
• Data (@adonisjs/lucid): migrations, models, relationships, the query builder, transactions, pagination, and schema rules.
• Validation (@vinejs/vine): the validation cookbook plus a catalog of every validator type.
• Authentication and authorization (@adonisjs/auth, @adonisjs/bouncer, @adonisplus/permissions): guards and route protection, policy-based authorization, and role-based permissions.
• Supporting packages: file uploads (@adonisjs/drive), email (@adonisjs/mail), sessions (@adonisjs/session), and the Inertia frontend layer (@adonisjs/inertia).

Several topics ship in per-stack variants. The controllers doc for a JSON API differs from the one for an Inertia React app, and the installer copies the variant that matches the rendering stack you chose at install time.

A catalog doc, packages.md, lists every supported package and the topics it owns. When the agent needs a doc that is not present, it reads packages.md to identify which package you would have to install before re-running the installer.

How an agent uses the knowledge base

The harness docs sit in .flow/docs/, but the agent finds them through the index Flow writes into your context file. That index, covered in the Installation guide, has three parts working together:

• A root pointer to the .flow/docs/ directory.
• A standing instruction to stop and read the relevant doc before relying on memory for any framework task.
• A topic list, one routing hint per doc. Each hint is phrased as "read when..." so the agent can match a task, such as "add a validator to this action", to the doc that covers it.

When the agent picks up a framework task, it consults the index, opens the matching doc from .flow/docs/, and treats that doc as the primary reference for the work. The spec-driven workflow skills lean on the same index: each planning step reads the docs relevant to that step.

How the docs are written

Harness docs follow a strict authoring discipline, because a doc that is too long or too vague is as unhelpful as no doc at all.

Every doc is one of two kinds. A cookbook doc covers a topic where the harness has an opinion. It walks the recommended path: what to do, which alternatives are acceptable and when, which patterns to avoid, and which are outright wrong. Most top-level docs, such as controllers, models, validation, and routing, are cookbooks. A reference doc covers a topic where the harness has no opinion, such as the full list of Vine validator types. It is a plain catalog with an anti-hallucination rule stated at the top: the list is complete, do not invent names outside it.

A cookbook doc follows a fixed section order, so the agent always knows where to look.

# Routing

## Contents

Read when defining, organizing, or extending routes in `start/routes.ts`.

- Defining handlers and controller-backed routes
- Validating and shaping route params

## Recommended Defaults

- Define routes in `start/routes.ts`. Import the router via
  `import router from '@adonisjs/core/services/router'`.
- Wire controller-backed routes via `[controllers.<Name>, 'action']`.

## Valid Alternatives

- Use inline route handlers when route logic is small and does not
  justify a controller.

## Avoid By Default

- ...

The Contents section opens with a "read when" trigger so a partial reader can decide quickly whether to keep going. Recommended Defaults is the path the agent should follow. Valid Alternatives, Avoid By Default, and Invalid Patterns draw the boundaries of that path, and Recipes carries short, self-contained code samples.

A single test guides the author of every doc: after reading it, can an agent write working code for the topic? Anything that does not serve that test, such as background, deep dives, or an exhaustive API tour, is left out.

Next steps

• Spec-driven development shows how the workflow skills read the knowledge base at each step.
• Installation covers selecting which packages get harness docs.