Build your first profile

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.

Skill level

Beginner

Time

About 10 minutes

Result

One valid custom issue page

Before you start

Install llmwiki 1.0 or later, then check the version in any directory. Run in: any directory
Does: confirms that the CLI is available
Writes: nothing

llmwiki --version

You should see: version 1.0.0 or later
If it fails: follow Installation, then open a new terminal.

Your five steps

Create an empty project and its profile.
Validate and understand the generated file.
Add your first issue.
Check what llmwiki recognizes.
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
Does: creates the tutorial project folder
Writes: issue-tracker-wiki/

mkdir issue-tracker-wiki

Run in: the folder where you keep projects
Does: enters the project
Writes: nothing

cd issue-tracker-wiki

Now create the smallest useful profile. Run in: issue-tracker-wiki/
Does: defines one kind of page called issues
Writes: .llmwiki/profile.json and wiki/issues/

llmwiki profile init issue-tracker --entity issues

You should see:

Created profile 'issue-tracker'
wrote .llmwiki/profile.json
created wiki/issues/
next: llmwiki profile validate

Checkpoint: both paths shown above exist.
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/
Does: checks that every profile rule is supported and internally consistent
Writes: nothing

llmwiki profile validate

You should see:

Profile 'issue-tracker' is valid

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.

macOS and Linux
PowerShell

Run in: issue-tracker-wiki/
Does: creates the first issue page
Writes: wiki/issues/explain-first-profile.md

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

Run in: issue-tracker-wiki/
Does: creates the first issue page
Writes: wiki/issues/explain-first-profile.md

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

Checkpoint: the new Markdown file exists under wiki/issues/.
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/
Does: checks existing pages against the profile rules
Writes: .llmwiki/last-lint.json

llmwiki lint

You should see:

0 error(s), 0 warning(s), 0 info

Then open the local read-only viewer. Run in: issue-tracker-wiki/
Does: starts a local viewer and asks your operating system to open it
Writes: nothing

llmwiki view --open

The port varies, so the readiness line looks like:

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.

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.

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.

{
  "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.

llmwiki profile validate

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

llmwiki lint

You should see:

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:

---
title: Explain the first profile
priority: normal
---

Run both checks again:

llmwiki profile validate

llmwiki lint

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

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.

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.
Follow AutoSci Research Workflow for artifacts, connectors, and research gates.
Follow Newsroom Editorial Workflow for a smaller editorial model.

Get Started

Core Concepts

CLI Reference

Configuration

Guides

Troubleshooting

Build your first profile

Skill level

Time

Result

Before you start

Your five steps

Step 1: Create the project

Step 2: Validate and understand the profile

Step 3: Add your first issue

Step 4: Check what llmwiki recognizes

Step 5: Add a rule and repair one issue

Where to go next

Skill level

Time

Result

​Before you start

​Your five steps

​Step 1: Create the project

​Step 2: Validate and understand the profile

​Step 3: Add your first issue

​Step 4: Check what llmwiki recognizes

​Step 5: Add a rule and repair one issue

​Where to go next

Before you start

Your five steps

Step 1: Create the project

Step 2: Validate and understand the profile

Step 3: Add your first issue

Step 4: Check what llmwiki recognizes

Step 5: Add a rule and repair one issue

Where to go next