> ## Documentation Index
> Fetch the complete documentation index at: https://llmwiki.atomicstrata.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Build your first profile

> Create a custom issue-tracker profile, add a valid page, and see llmwiki recognize it in about ten minutes.

export const profileExplanations = [{
  title: "File format version",
  key: "schemaVersion",
  lines: [2],
  description: "Tells llmwiki which version of the profile format this file uses.",
  importance: "Keep this at 1. llmwiki checks it before using any of the rules below."
}, {
  title: "Profile name",
  key: "profileId and displayName",
  lines: [3, 4],
  description: "Gives your project rules a stable internal name and a readable label.",
  importance: "The internal name is used by tools. The readable label is what people see."
}, {
  title: "Kinds of pages",
  key: "entities and issues",
  lines: [5, 6],
  description: "Declares that this project stores a kind of page called an issue.",
  importance: "You can add more page kinds later, such as projects, decisions, or customers."
}, {
  title: "Where pages live",
  key: "directory",
  lines: [7],
  description: "Places issue pages in the wiki/issues folder.",
  importance: "llmwiki uses this folder to recognize which rules apply to each page."
}, {
  title: "Required page title",
  key: "titleField, requiredFields, and fields.title",
  lines: [8, 9, 10, 11, 12, 13, 14, 15, 16],
  description: "Requires every issue page to include a title made from text.",
  importance: "If a page is missing its title, lint points to that page and explains the problem."
}];

export const starterProfileText = `{
  "schemaVersion": 1,
  "profileId": "issue-tracker",
  "displayName": "Issue Tracker",
  "entities": {
    "issues": {
      "directory": "wiki/issues",
      "titleField": "title",
      "requiredFields": [
        "title"
      ],
      "fields": {
        "title": {
          "type": "string"
        }
      }
    }
  }
}`;

Create a small custom profile in a real local project. You will define issue
pages, add one issue, check it, and make one controlled change to the rules.

<CardGroup cols={3}>
  <Card title="Skill level">Beginner</Card>
  <Card title="Time">About 10 minutes</Card>
  <Card title="Result">One valid custom issue page</Card>
</CardGroup>

## Before you start

Install llmwiki 1.0 or later, then check the version in any directory.

**Run in:** any directory<br />
**Does:** confirms that the CLI is available<br />
**Writes:** nothing

```bash theme={null}
llmwiki --version
```

**You should see:** version `1.0.0` or later<br />
**If it fails:** follow [Installation](/installation), then open a new terminal.

## Your five steps

1. Create an empty project and its profile.
2. Validate and understand the generated file.
3. Add your first issue.
4. Check what llmwiki recognizes.
5. Add a priority rule, see one useful warning, and repair the issue.

## Step 1: Create the project

Create and enter a new folder. Keep each command separate so it is clear which
step failed if your shell reports an error.

**Run in:** the folder where you keep projects<br />
**Does:** creates the tutorial project folder<br />
**Writes:** `issue-tracker-wiki/`

```bash theme={null}
mkdir issue-tracker-wiki
```

**Run in:** the folder where you keep projects<br />
**Does:** enters the project<br />
**Writes:** nothing

```bash theme={null}
cd issue-tracker-wiki
```

Now create the smallest useful profile.

**Run in:** `issue-tracker-wiki/`<br />
**Does:** defines one kind of page called `issues`<br />
**Writes:** `.llmwiki/profile.json` and `wiki/issues/`

```bash theme={null}
llmwiki profile init issue-tracker --entity issues
```

**You should see:**

```text theme={null}
Created profile 'issue-tracker'
wrote .llmwiki/profile.json
created wiki/issues/
next: llmwiki profile validate
```

**Checkpoint:** both paths shown above exist.<br />
**If it fails:** use an empty project. The command refuses to replace an active
profile or reinterpret existing wiki content. It never offers a force option.

## Step 2: Validate and understand the profile

**Run in:** `issue-tracker-wiki/`<br />
**Does:** checks that every profile rule is supported and internally consistent<br />
**Writes:** nothing

```bash theme={null}
llmwiki profile validate
```

**You should see:**

```text theme={null}
Profile 'issue-tracker' is valid
```

### Generated profile

```json theme={null}
{
  "schemaVersion": 1,
  "profileId": "issue-tracker",
  "displayName": "Issue Tracker",
  "entities": {
    "issues": {
      "directory": "wiki/issues",
      "titleField": "title",
      "requiredFields": [
        "title"
      ],
      "fields": {
        "title": {
          "type": "string"
        }
      }
    }
  }
}
```

1. **File format version (`schemaVersion`)** tells llmwiki which profile format the file uses.
2. **Profile name (`profileId`, `displayName`)** supplies a stable internal name and readable label.
3. **Kinds of pages (`entities`, `issues`)** declares that this project stores issue pages.
4. **Where pages live (`directory`)** places issue pages in `wiki/issues/`.
5. **Required page title (`titleField`, `requiredFields`, `fields.title`)** requires every issue to have a text title.

**Checkpoint:** you can identify where issue pages belong and which information
each issue must contain.

## Step 3: Add your first issue

Create `wiki/issues/explain-first-profile.md` with the following exact content.

<Tabs>
  <Tab title="macOS and Linux">
    **Run in:** `issue-tracker-wiki/`<br />
    **Does:** creates the first issue page<br />
    **Writes:** `wiki/issues/explain-first-profile.md`

    ```bash theme={null}
    cat > wiki/issues/explain-first-profile.md <<'EOF'
    ---
    title: Explain the first profile
    ---

    Explain why this project uses custom issue pages and what information every issue should contain.
    EOF
    ```
  </Tab>

  <Tab title="PowerShell">
    **Run in:** `issue-tracker-wiki/`<br />
    **Does:** creates the first issue page<br />
    **Writes:** `wiki/issues/explain-first-profile.md`

    ```powershell theme={null}
    $content = @'
    ---
    title: Explain the first profile
    ---

    Explain why this project uses custom issue pages and what information every issue should contain.
    '@
    $content = $content -replace "\r`n", "`n"
    [IO.File]::WriteAllText(
      "wiki/issues/explain-first-profile.md",
      $content + "`n",
      [Text.UTF8Encoding]::new($false)
    )
    ```
  </Tab>
</Tabs>

**Checkpoint:** the new Markdown file exists under `wiki/issues/`.<br />
**If it fails:** confirm that you are inside `issue-tracker-wiki/` and that Step
1 created `wiki/issues/`.

## Step 4: Check what llmwiki recognizes

First check the page against the active profile.

**Run in:** `issue-tracker-wiki/`<br />
**Does:** checks existing pages against the profile rules<br />
**Writes:** `.llmwiki/last-lint.json`

```bash theme={null}
llmwiki lint
```

**You should see:**

```text theme={null}
0 error(s), 0 warning(s), 0 info
```

Then open the local read-only viewer.

**Run in:** `issue-tracker-wiki/`<br />
**Does:** starts a local viewer and asks your operating system to open it<br />
**Writes:** nothing

```bash theme={null}
llmwiki view --open
```

The port varies, so the readiness line looks like:

```text theme={null}
Viewer ready at http://127.0.0.1:PORT
```

Open **Graph** and find `Explain the first profile`. The issue appears as a
typed graph node. This proves llmwiki recognized the file under your profile;
the current viewer does not open typed issue bodies as ordinary page routes.
Press `Ctrl+C` in the terminal when you are finished.

<Accordion title="The browser did not open">
  Run `llmwiki view` without `--open`, then copy the printed loopback URL into a
  browser. This is the normal approach over SSH, in a container, or on a headless
  machine.
</Accordion>

## Step 5: Add a rule and repair one issue

Open `.llmwiki/profile.json`. Add `priority` to `requiredFields`, then add its
definition beside `title` under `fields`. The complete result is below; the new
parts are the second required field and the `priority` definition.

```json theme={null}
{
  "schemaVersion": 1,
  "profileId": "issue-tracker",
  "displayName": "Issue Tracker",
  "entities": {
    "issues": {
      "directory": "wiki/issues",
      "titleField": "title",
      "requiredFields": [
        "title",
        "priority"
      ],
      "fields": {
        "title": {
          "type": "string"
        },
        "priority": {
          "type": "enum",
          "enum": ["low", "normal", "high"]
        }
      }
    }
  }
}
```

Validate the rules first.

```bash theme={null}
llmwiki profile validate
```

It succeeds because the profile is valid. Now check the existing issue:

```bash theme={null}
llmwiki lint
```

**You should see:**

```text theme={null}
warning .../wiki/issues/explain-first-profile.md Required field "priority" is missing from frontmatter.
0 error(s), 1 warning(s), 0 info
```

This warning is deliberate. Profile validation checks the rules themselves;
lint checks your pages against those rules.

Add one line to the issue's frontmatter:

```yaml theme={null}
---
title: Explain the first profile
priority: normal
---
```

Run both checks again:

```bash theme={null}
llmwiki profile validate
```

```bash theme={null}
llmwiki lint
```

**You should see:** `0 error(s), 0 warning(s), 0 info`.

<Check>
  You created a custom profile, added a page that follows it, changed one rule,
  and repaired the resulting warning. Every checkpoint is an ordinary project
  file that you can edit and commit.
</Check>

## Where to go next

* Add allowed status changes to model `open`, `in-progress`, and `done`.
* Add a `blocks` relation between issues.
* Add a triage workflow.
* Package your profile with [Profile templates](/configuration/profile-templates).
* Follow [AutoSci Research Workflow](/guides/autosci-research-workflow) for artifacts, connectors, and research gates.
* Follow [Newsroom Editorial Workflow](/guides/newsroom-editorial-workflow) for a smaller editorial model.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.