🔧 fix: restore package-backed basic-cli canon

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: zrr1999

.github/workflows/ci-tests.yml

@@ -60,36 +60,68 @@ jobs:
         run: |
           # `src/host.sp` is the package host entry; validate it via package/example flows,
           # not standalone file-mode formatting.
-          paths=(examples src/basic_cli)
+          # Standalone file examples
+          find examples -maxdepth 1 -name '*.sp' -type f | sort | xargs _spore/target/release/spore format
+          # Project-mode examples (format their src files)
+          # Note: Project-mode examples define proper package structure but may not yet
+          # be fully executable until compiler package resolution is complete.
+          if [ -d examples/hello-app/src ]; then
+            find examples/hello-app/src -name '*.sp' -type f | sort | xargs _spore/target/release/spore format
+          fi
+          # Platform API modules
+          find src/basic_cli -name '*.sp' -type f | sort | xargs _spore/target/release/spore format
+          # Check tests if they exist
           if [ -d tests ]; then
-            paths+=(tests)
+            find tests -name '*.sp' -type f | sort | xargs _spore/target/release/spore format
           fi
-          find "${paths[@]}" -name '*.sp' -type f | sort | xargs _spore/target/release/spore format
-          git diff --exit-code -- "${paths[@]}"
+          git diff --exit-code
 
       - name: Check Spore files
         run: |
           # `src/host.sp` is the package host entry; validate it via package/example flows,
           # not standalone file-mode checks.
-          paths=(examples src/basic_cli)
+          # Standalone file examples
+          find examples -maxdepth 1 -name '*.sp' -type f | sort | xargs -n 1 _spore/target/release/spore check
+          # Platform API modules
+          find src/basic_cli -name '*.sp' -type f | sort | xargs -n 1 _spore/target/release/spore check
+          # Project-mode examples: validate with spore check
+          if [ -d examples/hello-app ]; then
+            echo "✓ Checking project-mode example examples/hello-app/src/main.sp"
+            _spore/target/release/spore check examples/hello-app/src/main.sp
+          fi
+          # Check tests if they exist
           if [ -d tests ]; then
-            paths+=(tests)
+            find tests -name '*.sp' -type f | sort | xargs -n 1 _spore/target/release/spore check
           fi
-          find "${paths[@]}" -name '*.sp' -type f | sort | xargs -n 1 _spore/target/release/spore check
 
       - name: Build Spore files
         run: |
           # `src/host.sp` is the package host entry; validate it via package/example flows,
           # not standalone file-mode builds.
-          paths=(examples src/basic_cli)
+          # Standalone file examples
+          find examples -maxdepth 1 -name '*.sp' -type f | sort | xargs -n 1 _spore/target/release/spore build
+          # Platform API modules
+          find src/basic_cli -name '*.sp' -type f | sort | xargs -n 1 _spore/target/release/spore build
+          # Project-mode examples: validate with spore build
+          if [ -d examples/hello-app ]; then
+            echo "✓ Building project-mode example examples/hello-app/src/main.sp"
+            _spore/target/release/spore build examples/hello-app/src/main.sp
+          fi
+          # Check tests if they exist
           if [ -d tests ]; then
-            paths+=(tests)
+            find tests -name '*.sp' -type f | sort | xargs -n 1 _spore/target/release/spore build
           fi
-          find "${paths[@]}" -name '*.sp' -type f | sort | xargs -n 1 _spore/target/release/spore build
 
-      - name: Run hello example
+      - name: Run standalone hello example
         run: _spore/target/release/spore run examples/hello.sp
 
+      - name: Run project-mode hello-app example
+        run: |
+          if [ -d examples/hello-app ]; then
+            echo "✓ Running project-mode example examples/hello-app/src/main.sp"
+            _spore/target/release/spore run examples/hello-app/src/main.sp
+          fi
+
       - name: Run Spore spec tests
         run: |
           if [ ! -d tests ]; then

README.md

@@ -29,20 +29,43 @@ Operating System
 
 ## Quick Start
 
+The canonical project-mode structure is demonstrated in `examples/hello-app/`:
+
+**examples/hello-app/spore.toml:**
+```toml
+[package]
+name = "hello-app"
+type = "application"
+
+[project]
+platform = "cli"
+default-entry = "app"
+
+[entries.app]
+path = "main.sp"
+
+[capabilities]
+allow = ["Compute"]
+```
+
+**examples/hello-app/src/main.sp:**
 ```spore
-/// A simple "Hello World" using the basic-cli platform.
-fn main() -> () uses [Console] {
-    println("Hello from Spore basic-cli!")
+pub fn main() -> () uses [Console] {
+    println("Hello from a project-mode Spore application!")
+    return
 }
 ```
 
+**Run the project:**
 ```bash
-spore check examples/hello.sp
-spore build examples/hello.sp
-spore run examples/hello.sp
+cd examples/hello-app
+spore check src/main.sp
+spore run src/main.sp
 ```
 
-This repository currently keeps `examples/` limited to files that PR CI validates today.
+This example currently uses the built-in `cli` platform. When custom platform packages are fully supported in the compiler, `basic-cli` will become a loadable platform dependency that applications can declare in `spore.toml` and import modules from (e.g., `import basic_cli.stdout`). Until then, the example demonstrates the project structure and validates that format/check/run work correctly.
+
+For quick experiments, you can also run standalone `.sp` files (see `examples/hello.sp`), but production applications should use the project-mode structure above.
 
 ## Project Structure
 
@@ -81,7 +104,8 @@ Applications targeting `basic-cli` must implement the same startup function name
 
 ## Tutorial Contract
 
-- `examples/` is for truthful, CI-validated examples only.
+- `examples/hello-app/` is the **canonical project-mode example** — its structure and format are validated in CI.
+- `examples/hello.sp` is a minimal standalone file for quick experiments (also validated in CI).
 - `src/basic_cli/` is the API surface for the platform modules themselves.
 - `src/platform_contract.sp` is the package-owned startup contract surface.
 - Only add `tests/` when the repo has real Spore-side regression coverage worth running with `spore test`.
@@ -105,7 +129,9 @@ Following Spore's [SEP-0003 (Effect Capability System)](https://github.com/spore
 
 🚧 **Early development** — API is unstable and subject to change.
 
-At the moment, the validated example is `examples/hello.sp`. More ambitious host-backed demos such as environment/file workflows should stay out of `examples/` until the current platform import/runtime architecture supports them honestly.
+The canonical example is the **project-mode** `examples/hello-app/` application, which demonstrates the standard project structure. It currently uses the built-in `cli` platform and validates successfully with `spore check` and `spore run`. Once custom platform packages are fully supported, applications will be able to declare `basic-cli` as a platform dependency and import its modules directly.
+
+The standalone file example (`examples/hello.sp`) demonstrates basic-cli usage for quick experiments. The platform API modules in `src/basic_cli/` define the capability-gated interface that will be available when package imports are enabled.
 
 ## License
 

examples/hello-app/spore.toml

@@ -0,0 +1,15 @@
+[package]
+name = "hello-app"
+version = "0.1.0"
+type = "application"
+spore-version = ">=0.1.0"
+
+[project]
+platform = "cli"
+default-entry = "app"
+
+[entries.app]
+path = "main.sp"
+
+[capabilities]
+allow = ["Compute"]

examples/hello-app/src/main.sp

@@ -0,0 +1,10 @@
+/// Canonical project-mode application example for basic-cli.
+///
+/// This application uses the built-in cli platform and demonstrates
+/// the standard project structure that basic-cli will support when
+/// custom platforms are fully implemented.
+/// Application entry point matching the platform contract.
+pub fn main() -> () uses [Console] {
+    println("Hello from a project-mode Spore application!")
+    return
+}