Awal Mapping Example

A reference repository demonstrating how to use .awal-mapping.json to make any non-standard project structure compatible with Awal Terminal.

Why?

Awal Terminal expects AI components (skills, rules, prompts, agents, hooks, MCP servers) to follow a standard directory layout with common/ and stacks/ folders. If your project already has its own structure, you don't need to reorganize everything — just add a .awal-mapping.json file to tell Awal Terminal where things are.

This Repository's Structure

This repo uses a deliberately non-standard layout to show how mapping works:

├── .awal-mapping.json        ← Mapping file (the star of the show)
├── ai/
│   ├── assistants/
│   │   └── code-reviewer/
│   │       └── agent.json    ← Agent
│   ├── chat-prompts/
│   │   ├── summarize.md      ← Prompt
│   │   └── translate.md      ← Prompt
│   └── automation/
│       ├── lint-check.sh     ← Hook (pre-session)
│       └── format-on-save.sh ← Hook (before-commit)
├── guidelines/
│   ├── code-style.md         ← Rule
│   └── security.md           ← Rule
├── tools/
│   ├── search/
│   │   └── SKILL.md          ← Skill
│   └── refactor/
│       └── SKILL.md          ← Skill
├── servers/
│   └── context-server.json   ← MCP server
└── extras/
    └── quick-fix.prompt      ← Caught by file_transforms

Mapping Format Reference

Top-level fields

Field	Type	Description
version	number	Schema version (currently 1)
root	string?	Optional subdirectory to scope all paths to
mappings	array	List of path-to-type mapping entries
file_transforms	object?	Extension-to-type fallback map

Mapping entry fields

Field	Type	Description
path	string	Glob pattern to match files
type	string	Component type: skill, rule, prompt, agent, hook, mcp-server
stack	string?	Stack name (defaults to common)
name	string?	Explicit component name override
skill_file	string?	Custom skill entry file (defaults to SKILL.md)
agent_file	string?	Custom agent entry file (defaults to agent.json)
hook_phase	string?	Hook phase: pre-session, post-session, before-commit

Glob patterns

• * — matches any single path segment
• ** — matches any depth of nested directories
• *.ext — matches all files with the given extension

How matching works

Mappings are evaluated in order. Each file is matched by the first mapping entry whose glob pattern matches — subsequent entries won't apply to already-matched files.

file_transforms acts as a fallback for any files not matched by the mappings array. It maps file extensions to component types (e.g., ".prompt": "prompt").

Getting Started

1. Copy .awal-mapping.json into your own repository
2. Edit the mappings array to match your project's directory structure
3. Open your repository in Awal Terminal
4. Open the AI Components Manager — your components should appear correctly categorized

Editing Mappings Visually

Awal Terminal includes a visual mapping editor. Open the AI Components Manager and click the mapping icon to view, edit, and preview your mappings with matched files highlighted.