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 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

PreviousWorkflow NextContext

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 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

Quality CLI

Lint tells you a line is wrong. akan quality tells you the shape of the codebase is drifting: none of it is a syntax error, and none of it shows until someone measures.

What It Catches

Files Grown Too Long

A service past 500 lines, a Template or Zone past 800, or a Util past 1,000.

akan.file.recommended-max-lines

Helpers In The Wrong File

A helper function declared in order.service.ts next to OrderService.

akan.convention.service

Modules With No Server View

Its UI renders only from Template, Zone and Util, so all of it ships to the browser as JavaScript.

akan.ssr.module-missing-server-view

Markup In The Bundle

A client component wraps a large static subtree around one or two handlers.

akan.ssr.client-static-markup

Run it before a review, after a refactor, and after any change to a .tsx file. The render share is the one number a UI change can quietly lower.

Words Used On This Page

TermDescription

rule

One check, named akan.<scope>.<name>; every warning names the rule that raised it.

scope

The group a rule belongs to; there are six, and the output is sorted by scope name.

server render share

Of the JSX elements in ui/ and lib/, the percentage that renders on the server.

quality

Scan every app and library for code quality warnings, or measure the server/client render balance.

scan (default) prints every warning, then the SSR balance and the suggested rules.
ssr prints the SSR balance first, then only the warnings whose scope is ssr.

Signature

Arguments

actionStringdefault scanscan | ssr

Which report to print: scan covers everything, ssr the render balance alone.

Options

--formatStringdefault texttext | json

Short form -f; json prints the whole result for tools, each warning's fix included.

Notes

NameDescription

where to run

The workspace root, the folder holding package.json, tsconfig.json and .env.

what is read

.ts and .tsx under apps/ and libs/ except .d.ts, plus every *.abstract.md.

what is skipped

Paths matched by the root .gitignore, plus node_modules and .git.

exit code

Success whatever it finds, so it runs beside lint and typecheck without becoming a third gate.

Examples

What Scan Reports

Each warning says where, which rule, what is wrong and how to fix it. After the warnings come the SSR balance and the suggested rules, so one plain akan quality run covers both. A shortened run looks like this:

Terminal

One line per warning: <file>:<line>:1 - warning <rule>: <message>. A global warning has no single file, so it prints <global> instead.
Indented lines add detail. note: related location lists each place involved, and fix: says what to change.
Sorted by scope name, then by file and line, so the scopes below appear in this order.
Only need the render balance? akan quality ssr prints it first and keeps only the ssr warnings.

The Six Scopes

ScopeDescription

agent

Form fields that publish no agent tool because their setter is wrapped.

convention

A module file declaring what its role does not allow, such as a helper in .service.ts.

file

Per-file hygiene: length, scaffold leftovers, globals, component-file exports, //! markers.

global

The same exported name, or the same function body, in more than one file.

layout

Files and folders outside the allowed app, library and module layout.

ssr

The six render-balance rules, and the only scope akan quality ssr keeps.

With --format json

The JSON result has five fields. akan quality ssr --format json has the same shape, with warnings narrowed to scope ssr.

FieldDescription

workspaceRoot

Absolute path of the workspace that was scanned.

scannedFiles

How many files were read.

warnings

rule, scope, severity, message and fix, plus file, line and locations when known.

ssrBalance

One entry per row of the balance: scope, serverMass, clientMass, serverShare (0 to 1).

suggestedRules

The suggested rules that close the text output, as strings.

Rules By Scope

Look up a rule id from the output here. Rules that share a cause share a row.

RuleFires when

akan.agent.unpublished-form-setter

An arrow handler taking a value calls st.do.set…On…, so that field publishes no agent tool.

akan.convention.<role>

A top-level declaration the module file does not allow; the table below lists what it does.

akan.file.recommended-max-linesakan.file.max-lines

Over 500 lines for a service, 800 for a Template or Zone, 1,000 for a Util, 2,000 for any file.

akan.file.abstract-max-lines

An *.abstract.md is over 300 lines; keep only what the code cannot show.

akan.file.class-export-global-declaration

A file that exports a class declares something else at top level, other than <Class>Options.

akan.file.component-exportakan.file.component-internal-declaration

A component file exports a non-component, or keeps a local type or function besides <X>Props.

akan.file.bang-comment-in-client

A //! or /*! marker in browser code, which survives minification; write // FIXME:.

akan.file.placeholder-export

An index.ts exports a scaffold placeholder such as aa, dumb or someCommonLogic.

akan.file.dictionary-stale-text

A dictionary still holds scaffold text such as Order description.

akan.file.global-declarationakan.file.window-augmentationakan.file.prototype-mutation

A declare global, a Window interface or a .prototype. write; isolate it in one low-level file.

akan.global.duplicate-exported-function-name

Two files export a function or class with the same name.

akan.global.duplicate-exported-function-body

Exports with different names share one body; extract a single helper.

akan.layout.app-root-fileakan.layout.app-root-folderakan.layout.lib-root-fileakan.layout.lib-root-folder

A file or folder at an app or library root that is not on the allowed list.

akan.layout.lib-facet-file

A file directly in lib/ other than cnst.ts, option.ts and the other support files.

akan.layout.module-ui-file

A .tsx in a module folder whose name is not an allowed role, such as OrderCard.tsx.

akan.ssr.*

The six render-balance rules, listed in the next section.

What Each Module File May Declare

akan.convention.<role> fires on any top-level declaration outside this list. Shown for a model named Order:

FileAllowed at top level

order.constant.ts

OrderInput, OrderObject, LightOrder, Order, OrderInsight, and enumOf classes

order.dictionary.ts

export const dictionary

order.document.ts

OrderFilter, Order, OrderModel

order.service.ts

OrderService

order.signal.ts

OrderInternal, OrderSlice, OrderEndpoint

order.store.ts

OrderStore

What The Duplicate Checks Skip

Expected name repeats are exempt. Files in ui/ and page/, and module files, may reuse a name. An enumOf class in a .constant.ts may not.
Short bodies are not compared. A body counts as a duplicate only at 80 characters or more, with whitespace collapsed.

Server Render Share

The share is the part of your component JSX that renders on the server. Treat 50% as the floor and a falling share as a regression.

If a change moved markup to the client, say why in the PR or move it back.

How It Is Counted

Elements, not files. Each JSX tag, opening or self-closing, counts as one element.
The directive picks the side. Every element in a file that starts with "use client" counts as client; all others count as server.
One row per app and library, plus a workspace total when there are two or more.
A row under 50% ends with <- below the 50% target.

akan quality ssr prints the share first, then only the ssr warnings:

Terminal

Only ui/ and lib/ are measured. The share and the six rules read .tsx files under apps|libs/*/ui/ and apps|libs/*/lib/, minus tests. page/, webkit/, srvkit/ and common/ are left out, so a route file never moves the number, and neither does a "use client" added there.

The Six ssr Rules

RuleFires when

akan.ssr.unnecessary-use-client

The file has "use client" but no hook, event handler, store or browser API; delete it.

akan.ssr.client-static-component

A component in a client file renders 4+ JSX elements with no client-only capability.

akan.ssr.client-static-markup

10+ elements wrap only one or two interactive touches; the static part belongs on the server.

akan.ssr.client-mount-load

A useEffect(…, []) calls fetch.* or a loading st.do.* action; the route could load it first.

akan.ssr.module-missing-server-view

A module's client files render 12+ elements and it has no server Unit or View.

akan.ssr.template-client-state

A .Template.tsx calls useState, but a Template keeps its form state in the store.

Not Flagged On Purpose

Third-party code. A file importing a package, st or fetch is never told to drop "use client", and a component that renders a package's component is skipped.
A directive required by role. A module's Zone, Template and Util, and an index_.tsx lazy() boundary, are never an unnecessary "use client".
Loads the user starts. A fetch inside onClick, or an effect with dependencies, is not a mount-time load.
Service and scalar modules. Folders starting with _ under lib/ are never asked for a Unit or View.

Architecture · Frontend→

Each ssr rule with the code that triggers it and the fix that clears it.

akan lint→

Formats and lints one app, library or package with Biome.

akan typecheck→

Typechecks one app with TypeScript.

PreviousWorkflow NextContext