What This Guide Covers

This guide explains how to rewrite older Pinocchio config files to the current unified document model.

Use it when your config still contains legacy keys such as:

• repositories at the top level
• profile-settings.*
• ai-chat
• openai-chat
• claude-chat
• .pinocchio-profile.yml

The new model is intentionally stricter. Pinocchio now expects one unified config document with three semantic blocks:

• app
• profile
• profiles

That means old top-level runtime sections are not read anymore. If you leave them in place, Pinocchio will fail loudly instead of silently guessing.

The New Mental Model

The old model mixed several concerns together in one flat app config file:

• prompt repository locations
• active/default profile selection
• imported profile registries
• default provider/model settings
• provider-specific settings

The new model separates those concerns explicitly:

• app contains Pinocchio-owned application settings
• profile contains profile selection plus imported registry sources
• profiles contains inline engine-profile definitions stored directly in the config document

A minimal unified document looks like this:

app:
  repositories:
    - ~/code/prompts

profile:
  active: default

profiles:
  default:
    inference_settings:
      chat:
        api_type: openai
        engine: gpt-5-mini

Old-to-New Mapping

Use this table as the quick translation reference.

The most important migration rule is this:

There is no direct top-level replacement for old runtime sections.

If you previously kept model/provider defaults in top-level ai-chat or provider sections, move them into:

• an inline profile under profiles.<slug>.inference_settings, or
• an external engine-only profiles.yaml referenced from profile.registries

Step 1: Rename Local Project Files

If you have a repository-local or working-directory-local override file named:

.pinocchio-profile.yml

rename it to:

.pinocchio.yml

Pinocchio now rejects the old filename.

The supported local discovery order is:

1. git-root .pinocchio.yml
2. current-working-directory .pinocchio.yml
3. explicit --config-file

Step 2: Move Top-Level Repositories into app.repositories

Older config often used:

repositories:
  - ~/code/prompts
  - ~/.pinocchio/repository

Rewrite that to:

app:
  repositories:
    - ~/code/prompts
    - ~/.pinocchio/repository

This is the easiest part of the migration.

Step 3: Move profile-settings.* into profile.*

Older config often looked like this:

profile-settings:
  profile: assistant
  profile-registries:
    - ~/.config/pinocchio/profiles.yaml

Rewrite it to:

profile:
  active: assistant
  registries:
    - ~/.config/pinocchio/profiles.yaml

Use:

• profile.active for the selected/default profile slug
• profile.registries for imported engine-only registry sources

Step 4: Choose Inline Profiles or Imported Registries

At this point, you need to decide where the actual engine settings live.

Option A: Keep everything in one unified config document

This is the simplest migration when you previously had one personal config file with one default model.

Use inline profiles:

app:
  repositories:
    - ~/.pinocchio/repository

profile:
  active: assistant

profiles:
  assistant:
    display_name: Assistant
    inference_settings:
      chat:
        api_type: openai
        engine: gpt-5-mini

This is the best target when:

• you only need a few local profiles
• you want one file to control both app config and profile selection
• you do not need a shared team profile catalog

Option B: Keep engine profiles in profiles.yaml

This is the best target when you already have an external engine-profile registry file.

Unified app config:

app:
  repositories:
    - ~/.pinocchio/repository

profile:
  active: assistant
  registries:
    - ~/.config/pinocchio/profiles.yaml

External engine-only registry:

slug: workspace
profiles:
  assistant:
    slug: assistant
    inference_settings:
      chat:
        api_type: openai
        engine: gpt-5-mini

This is the best target when:

• you already share profiles.yaml across multiple commands or machines
• you want to keep the app config document small
• you want inline profiles only for local overrides, not for the main catalog

Step 5: Migrate Old Runtime Sections into profiles.<slug>.inference_settings

This is the part that usually causes confusion.

Older config often kept engine settings in top-level runtime sections such as:

ai-chat:
  ai-api-type: openai
  ai-engine: gpt-5-mini
openai-chat:
  openai-api-key: ...
claude-chat:
  claude-api-key: ...

Do not try to keep these at the top level. The unified document does not support that shape.

Instead, decide what role those settings were playing.

If they described your default model/provider

Create an inline profile and make it active:

profile:
  active: default

profiles:
  default:
    inference_settings:
      chat:
        api_type: openai
        engine: gpt-5-mini

If they belonged in a shared profile catalog

Move them into the engine-only profiles.yaml registry format and reference that file from profile.registries.

If they were shared credentials or cross-profile defaults

Prefer environment variables rather than copying secrets into every profile.

For example:

export OPENAI_API_KEY=...
export ANTHROPIC_API_KEY=...

This is usually cleaner than repeating credentials inside multiple inline profiles.

If you truly need profile-specific credentials, keep them under that profile's inference_settings. But avoid committing secrets to repository-local .pinocchio.yml files.

Concrete Before-and-After Examples

Legacy single-file config

repositories:
  - ~/.pinocchio/repository

profile-settings:
  profile: assistant
  profile-registries:
    - ~/.config/pinocchio/profiles.yaml

ai-chat:
  ai-api-type: openai
  ai-engine: gpt-5-mini

openai-chat:
  openai-api-key: <secret>

New inline unified config

app:
  repositories:
    - ~/.pinocchio/repository

profile:
  active: assistant

profiles:
  assistant:
    inference_settings:
      chat:
        api_type: openai
        engine: gpt-5-mini

Then keep credentials in the environment:

export OPENAI_API_KEY=<secret>

New unified config plus imported registry

~/.config/pinocchio/config.yaml:

app:
  repositories:
    - ~/.pinocchio/repository

profile:
  active: assistant
  registries:
    - ~/.config/pinocchio/profiles.yaml

~/.config/pinocchio/profiles.yaml:

slug: workspace
profiles:
  assistant:
    slug: assistant
    inference_settings:
      chat:
        api_type: openai
        engine: gpt-5-mini

Validation Checklist

After rewriting the config, validate it with an ordinary Pinocchio command.

Recommended checks:

1. Confirm the command still sees your prompt repositories.
2. Confirm the selected profile resolves correctly.
3. Confirm --print-inference-settings shows the expected final model/provider.
4. Confirm old filenames and old top-level keys are gone.

Example commands:

pinocchio examples test --print-inference-settings

pinocchio js --script examples/js/runner-profile-smoke.js --print-inference-settings

If you rely on a specific config file during the migration, use:

pinocchio --config-file ~/.config/pinocchio/config.yaml examples test --print-inference-settings

Common Migration Mistakes

Keeping profile-settings at the top level

This now fails. Rewrite it to profile.active and profile.registries.

Renaming the file but not the keys

Changing .pinocchio-profile.yml to .pinocchio.yml is necessary, but not sufficient. The document contents must also be rewritten.

Keeping ai-chat as a top-level block

There is no supported new top-level runtime block. Put model/provider settings under an inline profile or an imported engine-only registry.

Treating profiles.yaml as an app-runtime document

profiles.yaml is now engine-only. Keep prompts, tool choices, middleware choices, and repository settings out of it.

Troubleshooting

See Also

• Pinocchio Profile Resolution and Runtime Switching
• Pinocchio CLI Verb Migration Guide
• Webchat Engine Profile Guide
• JS Runner Scripts