# The project map (/project-map)



Jinion reads your project and keeps a map of it: what your files offer each other, how your code is written, and how
your interface looks. The agent uses it to reuse what exists and to write what it adds the way yours is written.

Nobody writes the map. Jinion builds it from the code, and reads a file again only when the file changed: as it
starts, after every turn, and before each lookup.

## What the map holds [#what-the-map-holds]

| Part                     | What it holds                                                                                                                   |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| What your files offer    | Components, hooks, functions, classes, types, constants, design tokens and styles, with where each is and how many files use it |
| How your code is written | How files are named, `interface` or `type` for object shapes, named or default exports, how functions are declared              |
| What it is built with    | The frameworks and libraries in your manifests, such as Next.js, Tailwind CSS or Bootstrap                                      |
| How it looks             | Your design tokens, the classes and style values your interface keeps to, and the colors written outside the tokens             |

A way of writing counts as your project's habit once at least 8 of 10 cases follow it, over at least 10 cases. Under
that the map says nothing, since the project hasn't chosen.

It reads JavaScript and TypeScript, Vue, Svelte and Astro components, React Native style objects, Swift and SwiftUI,
PHP and Blade, stylesheets and HTML templates. Files git ignores, and generated ones, stay out.

## How the agent uses it [#how-the-agent-uses-it]

* Before it writes a new component or helper, it looks for one that already does the job. You see a line such as
  `Look in the project map · relative time ago`.
* It writes what it adds the way the project is written: your file names, your declarations, your tokens and classes.
* Before its last message, the agent checks what the turn wrote against the map: a piece the project already had, a
  file named against the project's habit, a class or a color new to the project. It puts those right, or keeps them
  and says why, then ends with one short report. You see `Checked against the project · 2 things, 1 fixed`; open it for
  each point in plain words, with `Fixed` or `Kept`.

What you ask for by name stays as you asked. If you ask for `rounded-2xl` in a project that uses `rounded-lg`, you get
`rounded-2xl`, with a line saying the project didn't have it.

## Interface work [#interface-work]

On an interface the agent works as a design engineer: how it looks is yours to decide, the craft is its job.

* It builds from your project's own components, tokens and classes, starting from the existing piece most like the
  one you asked for.
* Before a new screen it says in two or three sentences what it understood, and waits for your yes.
* Where the project hasn't decided, such as the first screen of a new project, it doesn't pick a look. It asks what
  you find well made, then offers two or three named directions to pick from.
* It saves your pick to its [notes](/memory), with what you turned down, and applies it from then on.

Ask for options at any time:

```text
Show me three options for this card
```

## The agent looks at what it made [#the-agent-looks-at-what-it-made]

A build doesn't show whether an interface looks right, so the agent takes a picture and checks it. You see a line such
as `Look at the result · http://localhost:3000/settings`.

| It looks at         | It needs                                        |
| ------------------- | ----------------------------------------------- |
| A page              | Chrome, Chromium, Edge or Brave on your machine |
| The iOS simulator   | Xcode, with a simulator booted                  |
| An Android emulator | `adb`, with an emulator running                 |

The browser runs without a window, in a profile of its own, so your browser and what you are signed in to stay out of
it. Set `JINION_BROWSER` to the path of a browser that isn't where they usually are. Without one, the agent tells you
it couldn't look.

It only looks: it clicks and types nothing.

## Keep your habits with lint rules [#keep-your-habits-with-lint-rules]

When your linter, Biome or ESLint, has no rule for a habit the map found, the agent can add one. It offers once, after
it corrected something because of that habit, or when you ask how to keep the code alike. It adds the rule only when
you say yes.

## Find pieces by what they do [#find-pieces-by-what-they-do]

The map finds a piece by its name and its path. To find one by what it does, let the small model write a sentence on
each piece:

```json
{
  "describeMap": true
}
```

Put it in `~/.jinion/settings.json`. It is off by default, since it spends your plan's usage: the most used pieces
first, 30 to a request, and at most 300 pieces as Jinion starts and after each turn, until every piece has a sentence.
A sentence is written again only when the piece's code changes.

With it on, the review at the end of a turn also catches two names for one job. If the turn wrote a
`formatRelativeTime` and the project has a `timeAgo` that does the same, the agent is told, with one more request to
the small model for each new piece, up to three a turn.

## Where it is kept [#where-it-is-kept]

| File                                         | Holds                                   |
| -------------------------------------------- | --------------------------------------- |
| `~/.jinion/projects/<project>/map.json`      | The map                                 |
| `~/.jinion/projects/<project>/purposes.json` | The sentences, once `describeMap` is on |

Both come from your code. Delete them and Jinion builds them again. A conversation in a [worktree](/worktrees) reads a
map of its own folder, kept only while Jinion runs.