docs: student onboarding and safer Cortex credentials packaging

.github/workflows/verify-central.yml

@@ -6,6 +6,9 @@ on:
     branches: [main]
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 jobs:
   resolve:
     runs-on: ubuntu-latest

README.md

@@ -1,6 +1,5 @@
 # Getting Started with CORTEX4J
 
-
 ![Java 21+](https://img.shields.io/badge/Java-21%2B-blue)
 ![Version 0.2.0](https://img.shields.io/badge/version-0.2.0-green)
 [![Java CI](https://github.com/javiergs/cortex4j-getting-started/actions/workflows/java-ci.yml/badge.svg)](https://github.com/javiergs/cortex4j-getting-started/actions/workflows/java-ci.yml)
@@ -11,6 +10,8 @@ Learn to read EMOTIV headset data using **Cortex4J 0.2.0**, Java 21, and Maven.
 
 ## Quick start
 
+For a guided first experiment, see the [Student Quick Start](docs/student-quick-start.md). For commands, prerequisites, and expected output for every program, see [Runnable Examples](docs/examples.md).
+
 1. Install **JDK 21** and **Maven 3.9+**. Check with `java -version` and `mvn -version`; both should use Java 21.
 2. Follow [Setup](#setup) to configure EMOTIV Launcher, a headset or Virtual Brainwear, and your Cortex application credentials.
 3. In this repository's root folder, run:
@@ -52,7 +53,6 @@ This Getting Started repository already includes the dependency in its `pom.xml`
 
 **Do not commit your client secret.** Register your own Cortex application, subject to EMOTIV's account and licensing requirements.
 
-
 Your **Client ID and Client Secret identify your registered Cortex application**. They are **not** your EMOTIV account email address and password. Obtain them by following the application registration instructions in Setup step 3.
 
 For these Getting Started examples, store your Cortex application credentials in a local properties file.
@@ -67,7 +67,7 @@ cortex.client.secret=YOUR_CLIENT_SECRET
 
 3. Save the file and run an example. `CortexClient.connect()` automatically reads these credentials; no changes to the Java examples are necessary.
 
-The real `cortex4j.properties` is excluded by `.gitignore`. **Never commit credentials or distribute a JAR containing them.**
+The real `cortex4j.properties` is excluded by `.gitignore` and excluded from JAR packaging by Maven. Maven can still copy it into local `target/classes` for running examples, so **never commit credentials or share build output containing them**.
 
 **Optional:** Instead of a properties file, you can set `CORTEX_CLIENT_ID` and `CORTEX_CLIENT_SECRET` environment variables. If both are set, they take precedence over the properties file.
 
@@ -81,7 +81,6 @@ mvn clean compile
 
 This verifies the Java dependency setup but does not test headset access. Start EMOTIV Launcher, sign in, connect your headset or Virtual Brainwear, and approve the application before running an example.
 
-
 Device-status stream (recommended first test):
 
 ```bash
@@ -104,11 +103,14 @@ mvn compile exec:java -Dexec.mainClass=com.javiergs.examples.BandPowerExample
 
 These examples print raw ordered channel values. Sensor names and band-power channels are headset/stream-dependent; do not assume array indexes represent specific electrodes or frequency bands. The EEG stream may require additional licensing. All three require EMOTIV Launcher and a connected headset or Virtual Brainwear.
 
-
 The metrics example uses the documented channel ordering for known layouts; Cortex4J does not expose the `subscribe` response's `cols` metadata yet. For unknown layouts, the example prints raw values instead of guessing labels. Verify the reported labels against your headset and Cortex version. See [EMOTIV's sample format documentation](https://emotiv.gitbook.io/cortex-api/data-subscription/data-sample-object).
 
 Each program connects using `CortexClient`, registers a `CortexListener`, subscribes to a stream, prints samples for 30 seconds, and closes automatically. The example code is in `src/main/java/com/javiergs/examples/`.
 
+## Build checks
+
+The public **Java CI** workflow runs `mvn clean verify` with Java 21. The separate **Verify Maven Central dependency** workflow compiles with an isolated empty Maven cache to check that the published Cortex4J dependency resolves independently. Neither workflow requires EMOTIV credentials or tests headset connectivity.
+
 ## Troubleshooting
 
 - No headset: connect hardware or enable Virtual Brainwear.

docs/examples.md

@@ -0,0 +1,42 @@
+# Runnable Cortex4J examples
+
+All examples use **Java 21**, the public Maven Central dependency **com.javiergs:cortex4j:0.2.0**, and EMOTIV Launcher. Run commands from the repository root after following the [student quick start](student-quick-start.md).
+
+First verify the build:
+
+```bash
+mvn clean verify
+```
+
+| Example | Stream | What you observe | Important prerequisite |
+| --- | --- | --- | --- |
+| `DeviceExample` | `dev` | Headset ID, timestamps, device/status samples | Connected headset or available Virtual Brainwear |
+| `MetricsExample` | `met` | Named metrics for recognized layouts; otherwise raw values | Performance metrics stream entitlement |
+| `EegExample` | `eeg` | Timestamped, ordered raw EEG values | EEG-capable device and any required licensing |
+| `MotionExample` | `mot` | Timestamped motion values | Supported motion stream |
+| `BandPowerExample` | `pow` | Timestamped band-power values | Supported band-power stream |
+
+## Run an example
+
+```bash
+mvn exec:java -Dexec.mainClass=com.javiergs.examples.DeviceExample
+mvn exec:java -Dexec.mainClass=com.javiergs.examples.MetricsExample
+mvn exec:java -Dexec.mainClass=com.javiergs.examples.EegExample
+mvn exec:java -Dexec.mainClass=com.javiergs.examples.MotionExample
+mvn exec:java -Dexec.mainClass=com.javiergs.examples.BandPowerExample
+```
+
+Run **one command at a time**. Each example subscribes for about **30 seconds**, prints received samples, and closes the client. Actual samples depend on Launcher, the headset, stream availability, and permissions. Output may be absent if no data arrives.
+
+## Understanding the output
+
+- `DeviceExample` is the recommended first connectivity check.
+- `MetricsExample` recognizes the documented 13-value Insight/EPOC and 4-value MN8 layouts. Cortex4J 0.2.0 does **not** expose subscription `cols` metadata, so unknown layouts are printed without guessed labels.
+- `EegExample`, `MotionExample`, and `BandPowerExample` print **ordered raw values**. Do not assume a fixed array index always corresponds to a specific sensor or band.
+- A passing `mvn clean verify` checks the Java project and published dependency; it does **not** test a real headset or account entitlements.
+
+For stream-specific column definitions, consult the [EMOTIV sample format documentation](https://emotiv.gitbook.io/cortex-api/data-subscription/data-sample-object).
+
+## Student exercises
+
+Try displaying only timestamps and sample counts, comparing two permitted streams, or designing a listener that computes a rolling summary. Do not commit secrets, headset identifiers tied to participants, or identifiable recordings.

docs/student-quick-start.md

@@ -0,0 +1,70 @@
+# Student quick start
+
+This guide uses the published **Cortex4J 0.2.0** Java library. You do not need the library's implementation source.
+
+## 1. Prepare Java and Maven
+
+Install JDK 21 and Maven 3.9 or newer. From a terminal, check:
+
+```bash
+java -version
+mvn -version
+```
+
+Both should report Java 21. Clone or download this repository, then open a terminal in its root directory.
+
+## 2. Prepare EMOTIV
+
+1. Create an EMOTIV account, install **EMOTIV Launcher**, and sign in.
+2. Connect a supported headset, or set up **Virtual Brainwear** if available to your account.
+3. Register a Cortex application to obtain its **Client ID** and **Client Secret**.
+4. Approve application access in Launcher when prompted.
+
+Your Cortex application credentials are **not** your EMOTIV account password. Streams and Virtual Brainwear availability depend on your headset, account, and licensing.
+
+See the [EMOTIV application registration instructions](https://www.emotiv.com/knowledge-base/how-to-register-your-app-id-with-cortex-sdk-for-development).
+
+## 3. Configure credentials
+
+For a local experiment, copy `src/main/resources/cortex4j.properties.example` to `src/main/resources/cortex4j.properties` and replace the placeholders with your application credentials.
+
+The real properties file is ignored by Git and **excluded from packaged JARs**. Maven may still copy it into local `target/classes` for running examples; never share your build output. Do not commit or share it.
+
+Alternatively, set both `CORTEX_CLIENT_ID` and `CORTEX_CLIENT_SECRET` environment variables. These take precedence over the properties file. Prefer environment variables for independent applications and CI. Never print secrets or paste them into issues.
+
+## 4. Run the first example
+
+With Launcher running and a headset or Virtual Brainwear available:
+
+```bash
+mvn clean verify
+mvn exec:java -Dexec.mainClass=com.javiergs.examples.DeviceExample
+```
+
+`DeviceExample` connects, reports the headset ID, listens for device/status samples for about **30 seconds**, and closes the connection. A successful Maven build **does not** prove headset connectivity.
+
+## 5. Try another stream
+
+If your account permits performance metrics:
+
+```bash
+mvn exec:java -Dexec.mainClass=com.javiergs.examples.MetricsExample
+```
+
+Other examples cover EEG, motion, and band power. See the [examples guide](examples.md) for commands and limitations.
+
+## 6. Create your own project
+
+In a separate Java 21 Maven project, add:
+
+```xml
+<dependency>
+    <groupId>com.javiergs</groupId>
+    <artifactId>cortex4j</artifactId>
+    <version>0.2.0</version>
+</dependency>
+```
+
+Start with `CortexClient.connect()`, register a `CortexListener` for a stream, subscribe, and close the client when finished. Use the examples here as references, not as a required dependency.
+
+If something fails, see [README troubleshooting](../README.md#troubleshooting). Never include credentials or identifiable participant data in a bug report.

pom.xml

@@ -26,6 +26,17 @@
                 <artifactId>maven-compiler-plugin</artifactId>
                 <version>3.16.0</version>
             </plugin>
+            <!-- Keep local credentials available to exec:java, but never package them in a JAR. -->
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-jar-plugin</artifactId>
+                <version>3.4.2</version>
+                <configuration>
+                    <excludes>
+                        <exclude>cortex4j.properties</exclude>
+                    </excludes>
+                </configuration>
+            </plugin>
             <plugin>
                 <groupId>org.codehaus.mojo</groupId>
                 <artifactId>exec-maven-plugin</artifactId>