YouBothAgent▾

You — Business rules and flows you own. Read these yourself.

Both — Know the idea; your agent follows the details.

Agent — Conventions and references your agent follows. Look up as needed.

CLI Reference▾

Commands Workspace Application Library Module Scalar Package Page Primitive Workflow Quality Pipeline Context Agent Guideline

AkanJS Reference▾

akanjs/base akanjs/common akanjs/constant akanjs/fetch akanjs/signal akanjs/server akanjs/client akanjs/webkit

UI Reference▾

Overview Core Display Forms Overlays System Agent Customization

Primitive CLI

Three commands that add one field or one UI file to a module that already exists. They write the mechanical part people get wrong by hand: a dictionary label left out, an import never added, a component in the wrong file.

They are the steps the create-ui, add-field and add-enum-field workflows apply. Run them directly when you already know what you want.

Words Used on This Page

TermDescription

primitive

A command that writes one change you already decided on straight to source, with no plan step.

surface

The role of one module UI file — view, unit or template — picked with --surface.

report

What each command prints when it ends: the changed files, diagnostics, and what to run next.

workflow

The same change plus a plan to review first and checks to run after, compared at the end.

What Each Command Writes

Command

constant

.constant.ts

dictionary

.dictionary.ts

.tsx

Add a UI file

create-ui

✓

Writes one View, Unit or Template file and nothing else.

Add a field

add-field

✓

Adds the field to the Input class and its label to the dictionary.

add-enum-field

✓

Declares an enum class first, then adds a field typed as that class.

✓WrittenNot touched

Rules All Three Share

Missing options are not asked for. Leave out --app or --module and the command prints an error in its report instead of a prompt.
An error writes nothing. An unknown app, a missing input or a bad value leaves every file as it was, and the report names the cause.
You run sync and lint. The command only writes source. Its report lists akan sync <app> and akan lint <app> as the next steps.
--format json is for scripts and agents. It prints the same report as one JSON object.

create-ui

Write one UI file into lib/<module>/ of an existing module: a View, a Unit or a Template. It writes from the same template akan create-module uses, and touches no other file. It is the flag form of akan create-view, create-unit and create-template.

Signature

Options

--appStringrequired-a

Target app or library name.

--moduleStringrequired-m

Target module name, such as icecreamOrder.

--surfaceStringdefault templateview | unit | template · -u

Which file to write; Zone and Util are not built by this command.

--formatStringdefault markdownmarkdown | json · -o

markdown is for a person to read; json is the same report as one object.

Notes

NameDescription

view

<Module>.View.tsx exporting General, the detail screen, as a server component.

unit

<Module>.Unit.tsx exporting Card, one list or card item, as a server component.

template

<Module>.Template.tsx exporting the General form, with "use client" on line 1.

name field

The scaffold renders only the module's name field; swap in the fields you need.

existing file

A file already at that path is overwritten with the scaffold, so commit first.

afterwards

Run akan sync <app> and then akan lint <app>.

Examples

add-field

Add one field to a module's constant and dictionary. The field goes into <Module>Input in <module>.constant.ts, and its label and description into .model<Module> in <module>.dictionary.ts. For Int and Float it also adds the akanjs/base import.

Signature

Options

--appStringrequired-a

Target app or library name.

--moduleStringrequired-m

Target module, whose constant and dictionary files must both exist already.

--fieldStringrequired-f

Field name; a name already in the Input class is refused.

--typeStringrequired-t

Field type or scalar name; lowercase aliases such as int are normalized as listed in Notes.

--defaultString-d

Optional default, converted to the type; a value the type rejects writes nothing.

--formatStringdefault markdownmarkdown | json · -o

markdown is for a person to read; json is the same report as one object.

Notes

NameDescription

number aliases

int and integer become Int; float, double and decimal become Float.

other aliases

string, boolean and date are capitalized. Any other name is written as given.

Int · Float

number and numeric are refused: use Int for whole numbers and Float for decimals.

other imports

Only Int and Float get an import; add the one for ID or a scalar yourself.

file fields

Upload is refused, since it belongs only in a file-upload body; relate the field to File.

--default

Int/Float take a number, Boolean true/false, Date now or a date; others a string.

--default now

Writes () => dayjs(), so each record gets its own time; a date is written as a thunk too.

labels

The Korean label is filled in only for common words like status; otherwise it repeats the English.

components

No component is edited, so add the field to the Template form yourself.

afterwards

Run akan sync <app> and then akan lint <app>.

Examples

add-enum-field

Add a field that takes one value from a fixed set. First it declares the enum: an enumOf class named <Module><Field> in the constant, with the enumOf import added, and its options in the dictionary's .enum stage. Then it adds the field, typed as that class, exactly as add-field does.

Signature

Options

--appStringrequired-a

Target app or library name.

--moduleStringrequired-m

Target module, whose constant and dictionary files must both exist already.

--fieldStringrequired-f

Field name, which also names the enum: status on module order declares OrderStatus.

--valuesStringrequired-l

Comma-separated enum values, such as pending,serving,served.

--defaultString-d

Optional default, which must be one of --values.

--formatStringdefault markdownmarkdown | json · -o

markdown is for a person to read; json is the same report as one object.

Notes

NameDescription

no --type

The type is always the new enum class, which is why the command takes --values instead.

add-field --type enum

Fails and writes nothing, so a new enum always goes through add-enum-field.

existing enum

When the enum class already exists, run add-field --type <Class> instead.

option labels

Each value gets a Title Case English label in both languages, so translate the Korean ones.

afterwards

Run akan sync <app> and then akan lint <app>.

Examples

Primitive or Workflow

A primitive is one edit you already decided on. A workflow is the same edit, plus a plan you read first, the UI it can also touch, and a validation step after.

What you get

primitive

akan add-field

workflow

akan workflow plan

Both

the source edit

✓

The same field or UI file, written by the same code; a workflow calls these commands.

Workflow only

a plan to review

✓

You read what will change, then akan workflow apply writes it.

surfaces: ["template"]

✓

Writes the field into a simple Template form, passed only through MCP plan_workflow.

includeInLight: true

✓

Adds the field to the Light model too, and is also passed only through MCP.

akan workflow validate

✓

Runs sync and lint, plus typecheck after a field change, and sorts failures by cause.

✓IncludedNot included

When to Use Which

Primitive

akan add-field --field topping …

For a field you add while already working in the module. Two files, one command, no plan; you run sync and lint.

Workflow

akan workflow plan add-field … --out <path>

For a change you want to review before it is written. It is the shape agents are told to use.

Workflow→

The plan, apply, validate and repair chain, and every workflow.

Module→

Create the module itself with akan create-module.

PreviousPage NextWorkflow