> For the complete documentation index, see [llms.txt](https://stellarskills.gitbook.io/stellarskills-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stellarskills.gitbook.io/stellarskills-docs/configuration/files-and-workflow.md).

# files and workflow

All paths below are relative to the server's `config/stellarskills` directory.

| File or directory              | Purpose                                                             | Typical workflow                                           |
| ------------------------------ | ------------------------------------------------------------------- | ---------------------------------------------------------- |
| `general.yml`                  | Global language, client policy, HUD, safety and allocation switches | Edit file, validate/reload                                 |
| `storage.yml`                  | Database connection                                                 | Edit with server stopped; restart                          |
| `permissions.yml`              | Human-readable list of built-in permission nodes                    | Configure the actual permission provider                   |
| `classes.yml`                  | Classes, selection limits, Hero rules and class-menu theme          | File authoring, validate/reload                            |
| `leveling.yml`                 | XP curve, maximum level, level-point rewards and automatic sources  | Progression Studio or file authoring                       |
| `objectives.yml`               | XP quests and branching stories                                     | Progression Studio or file authoring                       |
| `features.yml`                 | Journey modules, rewards and leaderboard policy                     | File authoring, validate/reload                            |
| `journey_expansions.yml`       | Additional Journey modules merged into the suite                    | File authoring, validate/reload                            |
| `currencies/*.yml`             | Currency IDs, titles and balance caps                               | File authoring, validate/reload                            |
| `trees/*.yml`                  | Tree identity, theme, currency, lifecycle, metadata                 | Skill editor or file authoring                             |
| `graphs/*.yml`                 | Nodes, edges and labels                                             | Skill editor or file authoring                             |
| `themes/*.yml`                 | Registered theme identities and descriptors                         | Choose supported theme in a tree                           |
| `locale/*.yml`                 | Server-owned text for custom/fallback UI                            | File authoring, reload                                     |
| `effects/native_catalogue.yml` | Informational effect reference                                      | Does not register new effects                              |
| `integrations/*.yml`           | Integration reference files                                         | Effects belong in nodes/modules; bridge code owns behavior |
| `schemas/*.yml`                | Informational field guides                                          | Java parsing/validation is authoritative                   |
| `data/stellarskills.db`        | Default SQLite database                                             | Back up; never hand-edit while running                     |
| `backups/`                     | Editor publication revisions                                        | List/restore supported revisions                           |

## Stable IDs versus display names

IDs link persistent data and configuration: `capture_specialist`, `fire_method`, `story_intro`. Titles are what players read and may include colors/gradients. Keep IDs lowercase and stable. Renaming a quest, node, class, or module ID is not a cosmetic edit and does not automatically migrate player records.

Changing `title` is generally a presentation edit. Disabling old content is safer than recycling its ID for an unrelated reward. Node `aliases` are retained metadata; do not assume they automatically migrate database purchases.

## YAML essentials

* Use spaces, never tabs, for indentation.
* Quote hex colors and strings beginning with `#` or containing special YAML punctuation.
* Write booleans as `true`/`false` and quantities as numbers.
* Use a list for rank values: `values: [1.05, 1.10, 1.15]`.
* Effect `filters` contain scalar strings. Quest filters can also accept lists. Quote comma-separated parameter values.
* Keep one definition of each ID. Do not paste a second root `classes:` or `objectives:` map over an existing one.
* The parser accepts hyphen/underscore enum forms, but this guide uses the packaged conventions.

## Draft versus live content

Editor changes are server-held drafts. Validate catches invalid references, icons, counts, effects and policies. Publish requires separate permission and activates a validated revision. Other players continue using the live snapshot until publication succeeds.

Editor sessions are bound to the administrator, tree, token, revision and expiry. Opening a GUI is not enough to authorize edits. A second administrator publishing, a server reload, or session expiry can make your old session stale. Reopen rather than repeatedly submitting it.

Progression Studio publishes `leveling.yml` and `objectives.yml` together with recovery on activation failure. Skill publications also update tree/graph content and preserve revision backups. Backups are not a replacement for a full database/world backup.

## Safe file edits

{% stepper %}
{% step %}

### Save a copy

Save a copy of the affected files and database.
{% endstep %}

{% step %}

### Edit files

Edit files outside an active authoring session.
{% endstep %}

{% step %}

### Validate

Run `/skills admin validate` and inspect reported paths.
{% endstep %}

{% step %}

### Reload

Run `/skills admin reload`; wait for the activation result.
{% endstep %}

{% step %}

### Test

Reopen menus and test one ordinary player.
{% endstep %}
{% endstepper %}

A rejected staged reload preserves the live in-memory snapshot. It does not magically repair the edited files on disk. Restore/fix them before the next restart.

The full references in this book show shipped defaults, not values from your running server. Optional fields absent from a default may still be documented in their system guide or effect schema. Read [general policy and dormant descriptors](broken://pages/78a31310e19779132b070023c51e3c663092c914) before treating every `general.yml` value as a live tuning knob.