Refactoring

Author: nemicko

.github/workflows/pages.yml

@@ -0,0 +1,53 @@
+name: Deploy GitHub Pages
+
+on:
+  push:
+    branches: ["main", "master"]
+    paths:
+      - "site/**"
+      - "README.md"
+      - "specification.md"
+      - "registry/**"
+      - ".github/workflows/pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Build static site
+        run: |
+          mkdir -p _site
+          cp -R site/* _site/
+          cp README.md _site/README.md
+          cp specification.md _site/specification.md
+          cp -R registry _site/registry-files
+          touch _site/.nojekyll
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -0,0 +1,2 @@
+.DS_Store
+**/.DS_Store

CONTRIBUTING.md

@@ -5,15 +5,12 @@
 Community feature packages are published via pull requests to `registry/packages`.
 
 1. Create a package directory: `registry/packages/<feature>/`.
-2. Add `package.json` with required keys:
-   - `name`
-   - `version` (`x.y`)
-   - `summary`
-   - `files` (array of `.ail` file paths)
-3. Add package AIL files at package root.
+2. Add exactly one package entry file: `<feature>.intent`.
+3. Add optional facet files referenced by `INCLUDES` and/or inline intent payloads.
 4. Open a pull request.
+5. Update `registry/index.json` with `name`, `version`, and `entry`.
 
-CI validates package integrity and AIL header conventions.
+CI validates package integrity and AIM header conventions.
 
 ## Spec Changes
 

PROMPT.md

@@ -0,0 +1,34 @@
+# Generic AIM Synthesis Prompt
+
+Use this prompt in a local AI coding session:
+
+```md
+Implement one AIM package in this local project.
+
+Inputs:
+- PACKAGE: <package-name>
+- REF: <git-tag-or-commit>
+
+Steps:
+1. Fetch AIM spec:
+   https://raw.githubusercontent.com/juicejs/application-intent-language/<REF>/specification.md
+2. Fetch registry catalog:
+   https://raw.githubusercontent.com/juicejs/application-intent-language/<REF>/registry/index.json
+3. Resolve PACKAGE by `name` and fetch its `entry` file.
+4. Resolve and fetch optional details from:
+   - `INCLUDES` linked facets
+   - top-level inline facet blocks
+   - embedded facet payloads in `INTENT`
+   using AIM precedence/diagnostics rules from the spec.
+5. Materialize all fetched AIM sources into local:
+   - `./ail/` for feature files
+   - `./ail/mappings/` for mapping files (if present)
+6. Generate production-ready code from local `./ail` in this repository's detected stack.
+7. If any required reference is unresolved, stop and report precise gaps.
+
+If network fetch is unavailable, use local fallback:
+- ./specification.md
+- ./registry/index.json
+- package `entry` path from local index
+- local `./ail` as synthesis source of truth
+```

README.md

@@ -1,10 +1,10 @@
-# Application Intent Language (AIL)
+# Application Intent Model (AIM)
 
-AIL is an intent-first specification language for describing software features in a form that both humans and AI coding agents can use.
+AIM is an intent-first specification language for describing software applications in a form that both humans and AI coding agents can use.
 
 Start simple with one intent file, then add precision only where needed.
 
-## Why AIL
+## Why AIM
 
 - Keep product intent readable.
 - Keep synthesis deterministic.
@@ -14,14 +14,14 @@ Start simple with one intent file, then add precision only where needed.
 
 Each feature has one canonical intent file:
 
-- `<feature>.intent.ail`
+- `<feature>.intent`
 
 Optional precision facets can be added:
 
-- `<feature>.schema.ail`
-- `<feature>.flow.ail`
-- `<feature>.contract.ail`
-- `<feature>.persona.ail`
+- `<feature>.schema.intent`
+- `<feature>.flow.intent`
+- `<feature>.contract.intent`
+- `<feature>.persona.intent`
 
 This enables progressive detail:
 
@@ -56,7 +56,7 @@ To enable it in GitHub:
 ## Quick Example
 
 ```ail
-AIL: game.snake#intent@1.4
+AIM: game.snake#intent@1.4
 
 INTENT SnakeGame {
   SUMMARY: "A single-player snake game with top-10 scores."
@@ -76,12 +76,11 @@ INTENT SnakeGame {
 ## Repository Layout
 
 - [`specification.md`](./specification.md): canonical language specification
-- [`ail/`](./ail): example feature sources
-- [`ail/game.snake.intent.ail`](./ail/game.snake.intent.ail): intent envelope example
 - [`registry/`](./registry): feature package registry
-- [`registry/packages/`](./registry/packages): publishable feature packages
+- [`registry/index.json`](./registry/index.json): package catalog with intent entrypoints
+- [`registry/packages/`](./registry/packages): publishable feature packages (intent entry + optional facets)
 - [`CONTRIBUTING.md`](./CONTRIBUTING.md): contribution and publishing workflow
-- [`test/`](./test): test workspace and tooling
+- [`PROMPT.md`](./PROMPT.md): generic local AI synthesis prompt
 
 ## Current Demo
 
@@ -94,6 +93,17 @@ It is also published as a registry package:
 
 - [`registry/packages/game.snake`](./registry/packages/game.snake)
 
+## Local AI Fetch Flow
+
+Use this sequence:
+
+1. Fetch `specification.md`.
+2. Fetch `registry/index.json`.
+3. Select package by `name`.
+4. Fetch the package `entry` intent file and related facet files.
+5. Materialize fetched sources into local `/ail` (and `/ail/mappings` when needed).
+6. Synthesize from local `/ail` so users can edit and rebuild without refetching.
+
 ## Status
 
-Current spec version: **AIL v1.4**.
+Current spec version: **AIM v1.4**.

registry/README.md

@@ -1,6 +1,6 @@
-# AIL Feature Registry
+# AIM Feature Registry
 
-This directory is the publish surface for community AIL feature packages.
+This directory is the publish surface for community AIM feature packages.
 
 ## Package Layout
 
@@ -10,54 +10,48 @@ Each package lives in:
 
 Each package must contain:
 
-1. `package.json`
-2. One or more `.ail` source files at package root
+1. Exactly one intent entry file: `<feature>.intent`
+2. Optional additional facet files referenced by the intent file
 
-## `package.json` Schema
+## `registry/index.json` Schema
 
 Required fields:
 
+- `version`: index schema version
+- `packages`: array of package objects
+
+Each package object requires:
+
 - `name`: feature namespace (lowercase, dot-separated segments; single-segment allowed)
-- `version`: `x.y`
-- `summary`: short one-line description
-- `files`: array of relative `.ail` file paths (for package entry files)
-
-Example:
-
-```json
-{
-  "name": "game.snake",
-  "version": "1.3",
-  "summary": "Single-player snake game with top-10 leaderboard",
-  "files": [
-    "game.snake.intent.ail",
-    "game.snake.schema.ail",
-    "game.snake.flow.ail",
-    "game.snake.contract.ail",
-    "game.snake.persona.ail"
-  ]
-}
-```
+- `version`: `x.y` matching entry file header
+- `entry`: relative path to canonical intent file
 
 ## Pull Request Publishing Flow
 
 1. Fork and create a branch.
-2. Add or update a package in `registry/packages`.
-3. Open a PR.
-4. CI runs `scripts/validate_registry.py`.
-5. Maintainers review and merge.
+2. Add or update package files in `registry/packages/<feature>/`.
+3. Update `registry/index.json` with package `name`, `version`, and `entry`.
+4. Open a PR.
+5. CI runs `scripts/validate_registry.py`.
+6. Maintainers review and merge.
 
 Merged PRs are the publishing mechanism.
 
+## Consumption Model
+
+Consumers fetch package `entry` from this registry, resolve related sources, and materialize files into local project `/ail` (and `/ail/mappings` when applicable) before synthesis.
+
 ## Validation Rules
 
 CI enforces:
 
-- package manifest required fields
-- version format `x.y`
-- package name and directory match
-- listed files exist and end with `.ail`
-- each file uses `AIL: <feature>#<facet>@<x.y>`
+- index schema validity and non-empty package list
+- package/index consistency (one index record per package directory)
+- `entry` exists and points to `.intent`
+- entry header matches `name`, `intent` facet, and `version`
+- exactly one `*.intent` file per package directory
+- optional `INCLUDES` targets exist and match feature/facet/version
+- stale manifest files (`package.json`, `manifest.intent`) are rejected
 - legacy metadata tokens are rejected
 
 ## Notes

registry/index.json

@@ -4,12 +4,12 @@
     {
       "name": "game.snake",
       "version": "1.3",
-      "path": "registry/packages/game.snake"
+      "entry": "registry/packages/game.snake/game.snake.intent"
     },
     {
       "name": "weather",
       "version": "1.4",
-      "path": "registry/packages/weather"
+      "entry": "registry/packages/weather/weather.intent"
     }
   ]
 }

…kages/game.snake/game.snake.contract.ail …es/game.snake/game.snake.contract.intentregistry/packages/game.snake/game.snake.contract.ail renamed to registry/packages/game.snake/game.snake.contract.intent registry/packages/game.snake/game.snake.contract.ail renamed to registry/packages/game.snake/game.snake.contract.intent

@@ -1,4 +1,4 @@
-AIL: game.snake#contract@1.3
+AIM: game.snake#contract@1.3
 
 CONTRACT StartGame {
   INTENT:

…/packages/game.snake/game.snake.flow.ail …ckages/game.snake/game.snake.flow.intentregistry/packages/game.snake/game.snake.flow.ail renamed to registry/packages/game.snake/game.snake.flow.intent registry/packages/game.snake/game.snake.flow.ail renamed to registry/packages/game.snake/game.snake.flow.intent

@@ -1,4 +1,4 @@
-AIL: game.snake#flow@1.3
+AIM: game.snake#flow@1.3
 
 FLOW InitializeSession {
   INTENT:

…ackages/game.snake/game.snake.intent.ail …ry/packages/game.snake/game.snake.intentregistry/packages/game.snake/game.snake.intent.ail renamed to registry/packages/game.snake/game.snake.intent registry/packages/game.snake/game.snake.intent.ail renamed to registry/packages/game.snake/game.snake.intent

@@ -1,4 +1,4 @@
-AIL: game.snake#intent@1.3
+AIM: game.snake#intent@1.3
 
 INTENT SnakeGame {
   SUMMARY: "A classic single-player snake game where the player grows the snake, avoids collisions, and tries to reach the top-10 leaderboard."
@@ -12,10 +12,10 @@ INTENT SnakeGame {
 }
 
 INCLUDES:
-  - schema: game.snake.schema.ail
-  - flow: game.snake.flow.ail
-  - contract: game.snake.contract.ail
-  - persona: game.snake.persona.ail
+  - schema: game.snake.schema.intent
+  - flow: game.snake.flow.intent
+  - contract: game.snake.contract.intent
+  - persona: game.snake.persona.intent
 
 BEHAVIOR:
   - StartGame creates a new running session with deterministic initial snake state.