auto-eeg-analysis 0.3.3rc1__tar.gz

auto_eeg_analysis-0.3.3rc1/AGENT_GUIDE.md

@@ -0,0 +1,209 @@
+# AGENT_GUIDE.md — How LLM agents should drive AEA
+
+This file is the LLM-facing entry point. Read this *before* running any skill.
+
+## What AEA is
+
+AEA is an open library of EEG analysis skills for MNE-Python, with executable specifications and a numerically certified core. The agent reads each `SKILL.md` and generates analysis code in the user's environment. The repository also includes utility tools, EEGLAB / FieldTrip backend templates, worked examples, and tests. [Certification coverage](docs/CERTIFICATION_LEVELS.md) links the retained comparison records. You orchestrate; MNE-Python is the primary computation backend. Every step writes artifacts to disk so the pipeline survives compaction, crashes, and sleep.
+
+## Load the procedure before implementing it
+
+The resource index and skill descriptions route you to procedures; they do not
+contain the procedures themselves. Before writing EEG analysis code:
+
+1. Select relevant skills from [RESOURCE_INDEX.md](RESOURCE_INDEX.md) using the supplied research task.
+2. Open their `SKILL.md` files for required inputs, essential rules and section
+   routing. Read the matching sections in `references/procedure.md` for code
+   and numerical conventions; consult `references/background.md` when the
+   method needs explanation. For a recipe, also open its referenced skill
+   procedures. If tool output is truncated, read the remaining relevant
+   sections in separate chunks; a printed file prefix is not the whole skill.
+3. Record the files and sections used with the generated analysis, including
+   where the explicit task overrides an example or default. Do not claim a
+   procedure or independent check was applied merely because it was listed.
+
+For a bounded calculation, apply the relevant procedure to the supplied inputs;
+do not invent completed upstream stages or researcher approvals to satisfy an
+example directory layout. Scientific choices still follow the approved plan.
+
+For an explicit approved ERP plan, `tools/prepare_erp_packet.py` selects the
+matching execution section and callable helpers, adding group statistics only
+for group requests. See [approved ERP execution](docs/APPROVED_ERP.md).
+For its four explicit ERP CORE mean-amplitude contrasts, run the saved
+`tools/run_erp_plan.py` entry with the actual plan, input and workspace paths.
+It checkpoints participants, runs the requested tests and checks the saved
+delivery before writing `FINAL_SUBMISSION.md`. Read that actual file for the
+final response. Inspect the recorded PID and state after a timeout before
+resuming a stopped execution. Other ERP tasks retain their matching procedures.
+Complete readable metadata checks and fix programming errors within the already
+approved steps. Missing variable names or normal integer-sample epoch rounding
+do not require renewed scientific approval. Save actual computed artifacts before
+additional diagnostics; do not treat a check not yet run as a reason to stop the
+whole task. A genuinely missing input or unresolved scientific choice still
+blocks the affected step and must be recorded while independent work continues.
+
+For a client without native skill loading, the runner can use
+`tools/load_skill.py` to select a skill section and its relevant references,
+then include that complete procedure in the initial model message. This avoids
+losing it to tool-output truncation. Record the source paths and check the
+complete packet in the provider-format request. Keep that check separate from
+evidence that generated code followed the procedure. Changing from autonomous
+discovery to preloaded procedures is a distinct execution condition and must be
+recorded as such in an evaluation.
+
+The section loader follows the entrypoint's explicit reference links and returns
+the requested section with its actual source path. Omitting `--section` returns
+only the compact entrypoint, not all its supporting procedures.
+
+For an approved MNE continuous GFP, Welch/band-power or Hilbert plan, use
+`tools/run_continuous_plan.py` with the resolved public plan. It executes the
+ordered operations, records actual input/output dimensions, writes the complete
+result and final JSON, and checks the source data. See the
+[complete continuous route](docs/PRELOADED_SKILLS.md#execute-and-check-a-complete-continuous-plan).
+Keep processing extent separate from the saved interval. The task determines
+the operation order and power definition; this runner adds no study defaults.
+
+For a selected set of procedures and callable templates, use
+`tools/prepare_skill_packet.py`; see [preloaded procedure setup](docs/PRELOADED_SKILLS.md).
+The public artifact self-check checks structure and internal consistency, and
+can recompute selected operations from the unchanged input when their explicit
+public settings are supplied. Its `coverage` records what actually ran. Keep
+that record separate from packet delivery and independent numerical verification.
+
+## Project layout you will encounter
+
+```
+projects/<study-name>/
+├── DATASET_BRIEF.md          # filled by user — paradigm, subjects, channels, conditions
+├── ANALYSIS_PLAN.md          # claim-driven plan (you may help draft, user must approve)
+├── ENVIRONMENT.json          # produced by tools/env/check_env.{sh,ps1}
+├── raw/                      # original .bdf/.set/.edf/.fif (read-only)
+├── bids/                     # BIDS-converted (eeg-bids output)
+├── preprocess-stage/         # filtered, re-referenced, bad-chan-marked .fif
+├── ica-stage/                # .ica, ICLabel decisions, before/after PSD
+├── epoch-stage/              # epoched .fif + AutoReject decisions
+├── erp-stage/                # evoked .fif per condition + GFP
+├── tfr-stage/                # tfr_morlet.h5
+├── stats-stage/              # cluster_perm.json, results.csv
+├── figure-stage/             # *.svg / *.png (paper-ready)
+├── report-stage/             # REPORT.md + report.html (mne.Report)
+├── audit-stage/              # AUDIT.md (cross-model verdict)
+└── FINDINGS.md               # accumulated key results across stages
+```
+
+## The 6 rules
+
+### 1. Auto-brief first, ask second
+
+When the user points you at a `raw/` directory without a `DATASET_BRIEF.md`, run `python tools/auto_brief.py` to extract what the file headers tell you (channels, sampling rate, events, format, system). Then ask the user **only** about what you couldn't infer — paradigm, condition→marker mapping, epoch window, hypothesis. Do NOT dump a 9-section template and say "please fill this in". Conversational, targeted questions only.
+
+### 2. Read environment before claiming a backend works
+
+Always read `ENVIRONMENT.json` before invoking a FreeSurfer-dependent path. If a required package is missing:
+- **Degrade explicitly**: log the issue to the stage's `*.json`, and surface it in the eventual `AUDIT.md`.
+- **Never silently skip**: the user must see what is missing and how it affects the analysis.
+
+### 3. Use an approved plan for the current task
+
+A full study keeps its frozen `ANALYSIS_PLAN.md`: condition contrast, channels/ROI,
+time window, frequency band and statistical test, with planned direction when
+the study has one. A bounded request with already resolved scientific choices
+can supply that plan directly or as approved JSON; save it with the outputs.
+Do not invent epochs, contrasts, hypotheses or new approvals for a single
+calculation. Missing consequential choices still follow the researcher-decision
+policy. Contradictory results remain negative findings; do not retroactively
+edit the plan to make the result fit.
+
+Recipe defaults are proposals until approved for this study. In an explicitly
+unattended run, proceed through already approved steps; record missing scientific
+choices as blocked work and continue independent approved units. Do not resolve
+them by treating example values, a timeout or automatic execution as approval.
+Keep the actual plan and skill/recipe version with the run. Saved ICA exclusions
+refer to their saved decomposition, not to the same component indices in a new fit.
+
+### 4. Artifact-first, in-memory-second
+
+Every stage writes to disk before returning. If the agent crashes mid-pipeline, the next invocation re-reads the most recent stage output and continues. Re-runs retain the approved configuration and their comparison records; seeds alone do not guarantee identical ICA fits across numerical environments.
+
+Save the actual executed program and arguments as described in [Replay](docs/REPLAY.md).
+After a tool or terminal timeout, inspect the recorded PID, current process state,
+log and saved artifacts before any retry. A timeout is not proof that a worker
+stopped, and a missing variable is not proof that the whole session was lost.
+The saved-script runner offers `tools/replay.py status --out RUN_DIRECTORY`;
+it does not authorize a retry or certify scientific completion. Preserve failed
+directories and use a new output directory for a revised execution.
+
+### 5. The audit step is non-optional
+
+`eeg-audit` uses the approved configured reviewer with the plan, stats and figures.
+Read [project run settings](docs/RUN_SETTINGS.md) for the connection/model and
+[reviewer setup](docs/GETTING_STARTED.md#configure-the-reviewer) for supported
+connections. Record actual access, execution and verdict; do not silently switch
+models or treat an unavailable reviewer as passing. The complete-study audit
+requirement remains; the loader itself performs no review.
+
+Use direct checks for objective numerical, contract and artifact agreement. The
+model review complements those checks and does not replace independent
+recomputation or certify arbitrary report prose.
+
+### 6. GUI tools are not driven, only consumed
+
+If the user mentions Brainstorm / BrainVision Analyzer / Curry / Neuroscan, ask them to export to `.set` (EEGLAB), `.fif` (MNE), or `.bdf/.edf` (raw). Do not attempt to script GUI applications.
+
+## Skill invocation order (typical)
+
+```
+/eeg-bids        →  raw/ → bids/
+/eeg-preprocess  →  bids/ → preprocess-stage/
+/eeg-ica         →  preprocess-stage/ → ica-stage/
+/eeg-epoch       →  ica-stage/ → epoch-stage/
+/eeg-erp /eeg-tfr /eeg-connectivity /eeg-microstate /eeg-source  → epoch-stage/ → <stage>-stage/
+/eeg-stats       →  <stage>-stage/ → stats-stage/
+/eeg-figure      →  stats-stage/ + erp-stage/ + … → figure-stage/
+/eeg-report      →  all stages → report-stage/
+/eeg-audit       →  all stages → audit-stage/
+```
+
+`/eeg-pipeline` chains these and handles gates between stages.
+
+## Backend defaults
+
+| Skill | Default | When to override |
+|---|---|---|
+| eeg-preprocess | `mne` | `--prefer eeglab` / `--prefer fieldtrip` — both validated on all 5 certified components |
+| eeg-ica | `mne` (mne-icalabel) | EEGLAB ICLabel exists but agreement with mne-icalabel is **unmeasured** |
+| eeg-stats | `mne` | FieldTrip cluster partitions and observed t-maps have been compared for N400, P3b, N170, and ERN at the tested configurations; see [certification coverage](docs/CERTIFICATION_LEVELS.md) |
+| eeg-microstate | `pycrostates` | — |
+| eeg-source | `mne` + FreeSurfer | Brainstorm exports can be consumed via `scipy.io.loadmat` |
+
+**MNE-Python is the default and the reference backend.** EEGLAB and FieldTrip provide independent
+validation and are *selectable alternatives* for ERP preprocessing, validated
+against the reference on all five certified ERP CORE components
+([CROSS_TOOLBOX_EVAL.md](https://github.com/dengzhe-hou/auto-eeg-analysis/blob/995f53d42cc74205b164e8711d4b289b8c2ad3a1/tools/benchmark/CROSS_TOOLBOX_EVAL.md): 10/10 runs reproduce the group
+conclusion).
+
+Never pick one by hand. Run `tools/env/resolve_backend.py`, which writes `BACKEND_RESOLUTION.md`,
+fails loudly when nothing is available, refuses to switch silently away from a certified reference,
+and refuses to claim equivalence that was never measured. When it resolves to a non-MNE backend,
+emit `templates/backends/erp_preprocess_{eeglab,fieldtrip}.m` rather than ad-hoc code: cross-toolbox
+agreement is a property of how completely the specification is pinned, not of the toolbox.
+
+## Things to never do
+
+- Run analyses on data without `ENVIRONMENT.json` checked first.
+- Edit `ANALYSIS_PLAN.md` after a stage has run (creates retro-fit bias).
+- Skip `eeg-audit` because results "look reasonable".
+- Drive GUI applications via accessibility / AppleScript / keyboard automation.
+- Use a backend that the env probe didn't confirm — degrade explicitly instead.
+- Switch backends without re-running `resolve_backend.py` and updating `BACKEND_RESOLUTION.md`.
+- Write EEGLAB/FieldTrip code that leaves the filter cutoff convention, transition width, or
+  rejection criterion to the toolbox default. Unstated is not neutral — it is silent, and it moved
+  per-subject amplitudes by up to 43% of the group effect in AEA's own measurements.
+- Describe two backends' outputs as equivalent when `backends.json` records the agreement as
+  unmeasured.
+- Use a different random seed across stages without recording it (cluster perm is RNG-sensitive).
+- Report a p-value without recording the number of permutations and the cluster-forming threshold.
+
+## When in doubt
+
+Read the relevant `skills/eeg-*/SKILL.md`. If still unclear, ask the user — do not improvise on EEG-specific decisions (filter cutoff, reference scheme, ICA component count, etc.). These are paradigm-dependent and the user knows their data.

auto_eeg_analysis-0.3.3rc1/CHANGELOG.md

@@ -0,0 +1,115 @@
+# Versions and changes
+
+## Choose a version
+
+The website and setup commands describe **`main`**, which includes fixes and examples
+added after the latest tagged release, **v0.3.2**. The tag is a fixed historical
+snapshot; it does not receive later fixes.
+
+- **Use `main`** for the current instructions, saved-analysis replay helpers and
+  complete N400 tutorial. Record the commit used for each study.
+- **Use `v0.3.2`** when reproducing that release's specifications. Keep its original
+  configuration and study environment; the current tutorial scripts are not in it.
+  The [coverage record](docs/CERTIFICATION_LEVELS.md) identifies certified outputs
+  and configurations. A newer checkout does not certify every generated analysis.
+
+For a separate checkout of the fixed release:
+
+```bash
+git clone --branch v0.3.2 --depth 1 https://github.com/dengzhe-hou/auto-eeg-analysis.git aea-v0.3.2
+```
+
+Follow the setup guide **inside that checkout**. Do not mix instructions from `main`
+with missing helpers in the older release.
+
+## Changes on main since v0.3.2
+
+These changes have not been assigned a new library release tag. EEGLAB plugin
+previews use separate tags.
+
+- Added Simplified Chinese and Japanese READMEs and homepages, with language
+  links, localized navigation and copy feedback. Detailed technical guides,
+  skill/recipe source and EEGLAB menus remain primarily in English.
+
+- Released EEGLAB plugin preview 0.1.3 with a selectable native
+  MATLAB route: EEGLAB preparation/readback, Codex/Claude terminal launch and
+  explicit epoched ERP means with figures, HTML report and fresh-process replay.
+  This route does not require Python/MNE; the existing MNE route remains available.
+  Native runtime and desktop checks passed on the fixed Windows synthetic case.
+  Real Claude Code generated and executed a study-local MATLAB entry point;
+  independent first-delivery checks and fresh-process replay passed. It also
+  read documented reference values, so this is functional known-answer evidence,
+  not blind evaluation. All skills are not translated to MATLAB.
+  See the [plugin preview](https://github.com/dengzhe-hou/auto-eeg-analysis/releases/tag/eeglab-v0.1.3-preview).
+  AEA 0.1.3 was approved by the EEGLAB team and listed in the
+  [official extension catalogue](https://sccn.ucsd.edu/eeglab/plugin_uploader/plugin_list_all.php)
+  on 2026-10-29. Install it through **File > Manage EEGLAB extensions**,
+  then configure the separate AEA checkout and coding client. The library
+  release remains v0.3.2.
+
+- Added a preview EEGLAB extension with a Tools menu, dataset/event/history
+  export, study preparation, interactive Codex/Claude handoff and a report entry.
+  Automated checks exercise real EEGLAB/Octave exports and MNE import. MATLAB
+  desktop synthetic workflows with real Codex and Claude clients have passed
+  independent result checks and replay on Windows. Catalogue registration was
+  pending for 0.1.2; approval for 0.1.3 is recorded above. Plugin preview 0.1.2 packages the tested export-menu
+  fix. Its companion Python bridge and Windows startup fix come from the updated
+  AEA checkout. The library release version remains v0.3.2.
+- Reorganized all 22 skills into compact entrypoints with detailed procedures
+  and method background loaded from linked reference files. Added section loading
+  with source receipts, a channel-identity check before average referencing,
+  a memory-bounded SampEn helper and a bounded structured ERP report checker.
+  Checks have stated scopes; they do not certify arbitrary generated workflows.
+- Spectral templates now require the task's or approved plan's scientific
+  settings, including Welch segment/taper/overlap/FFT/DC choices, requested band
+  definitions and aggregation, and the selected alpha estimator. Example values
+  are labelled; short epochs and missing dependencies no longer silently change
+  the approved estimator or segment duration. Existing saved runs are unchanged.
+- Redesigned the homepage and README around the library, quickstart and worked
+  examples; retained the validation coverage and original evidence links.
+- Corrected time-frequency baseline units, Morlet
+  padding and the explicit `zero_mean` setting; separated constant segments,
+  low-amplitude warnings and rapid-change diagnostics in QC. These changes can affect newly
+  generated scripts and results. See [TFR](skills/eeg-tfr/SKILL.md) and
+  [QC](skills/eeg-qc/SKILL.md) for the current conventions.
+- Corrected N100 trial pairing and Flankers inference,
+  including restricted permutations. Original and corrected results, assumptions
+  and source snapshots remain linked from [Worked examples](docs/EXAMPLES.md).
+- Added saved-code/environment capture and replay, a tested
+  Linux package snapshot, and expanded numerical/API checks. See
+  [Replay](docs/REPLAY.md) and [Platform support](docs/PLATFORM_SUPPORT.md).
+- Added the complete fixed-cohort N400 recipe runner, saved numerical
+  results and compact arrays for figure reproduction without raw EEG. The runner
+  reads the official OSF `ses-N400` layout and existing sessionless caches directly.
+  Full runs check figure fonts before reading EEG or creating outputs; statistical
+  replay does not require fonts. Setup distinguishes this fixed tutorial from the
+  agent workflow and includes a copy-ready N400 dataset brief. Full runs also
+  check all 20 participants' required input files before reading EEG or creating
+  outputs, print stage progress, and document failure retries and completion checks.
+- Corrected ICLabel probability shapes and class-name
+  examples. Full seven-class probabilities require `iclabel_label_components`;
+  the existing component-rejection logic was unchanged.
+- Focused the default tree on the library, added a workflow
+  diagram and N400 figure, and clarified data preparation, study adaptation and help.
+  Historical research materials remain accessible through existing source snapshots.
+
+The [commit comparison](https://github.com/dengzhe-hou/auto-eeg-analysis/compare/v0.3.2...main)
+contains the complete changes.
+
+## Update an existing checkout
+
+Save your local edits first. From a checkout on `main`:
+
+```bash
+git pull --ff-only
+python tools/install_skills.py --agent codex
+```
+
+Use `--agent claude` for Claude Code, then restart the client. Existing linked skills
+track file changes automatically; rerunning the installer also discovers new skills.
+The general `environment.yml` is unchanged from v0.3.2. If a later update changes it,
+follow its setup instructions in a separate environment before starting a new study.
+
+An update changes the instructions the agent reads. It does not rewrite a saved
+program or reproduce previous results automatically. Keep completed studies' code,
+plans and captured environments unchanged; use [replay](docs/REPLAY.md) to rerun them.

auto_eeg_analysis-0.3.3rc1/CITATION.cff

@@ -0,0 +1,28 @@
+cff-version: 1.2.0
+title: "Automated EEG Analysis (AEA)"
+message: "If you use this software in your research, please cite it as below. If you used a specific recipe, also cite the source paper declared in that recipe's citation.bib."
+type: software
+authors:
+  - family-names: Hou
+    given-names: Dengzhe
+    affiliation: Tohoku University
+repository-code: "https://github.com/dengzhe-hou/auto-eeg-analysis"
+abstract: >
+  AEA is an open library of EEG analysis skills for MNE-Python, with executable
+  specifications and a numerically certified core. It provides shareable
+  paradigm-specific recipes, automatic COBIDAS-MEEG methods-text generation,
+  and a pre-submission reviewer-anticipation audit. EEGLAB and FieldTrip provide
+  independent validation and selected alternative backend paths.
+keywords:
+  - EEG
+  - electroencephalography
+  - reproducibility
+  - LLM agent
+  - Claude Code
+  - automated analysis
+  - MNE-Python
+  - EEGLAB
+  - FieldTrip
+license: MIT
+version: 0.3.2
+date-released: 2026-10-03

auto_eeg_analysis-0.3.3rc1/CONTRIBUTING.md

@@ -0,0 +1,122 @@
+# Contributing to AEA
+
+Contributions can add an analysis recipe, improve a skill, fix code and documentation, share a community tutorial, or report a first run on your platform. Start with [Getting started](docs/GETTING_STARTED.md) to set up the environment and load the skills. The [recipe library](recipes/README.md) lists the existing analyses; the [backend registry](tools/env/backends.json) records available backend capabilities.
+
+## Your first pull request
+
+1. Fork this repository, clone your fork, and create a branch for one focused change. A confusing instruction, a reproducible bug, or a missing method reference is a useful starting point.
+2. Follow the relevant contribution section below. Keep the source references, analysis choices, and existing results visible when changing a skill or recipe.
+3. Run the checks relevant to your change and record their outcomes. Documentation fixes can be reviewed through the diff and changed links; they do not require an EEG dataset or a model account.
+4. Open a pull request against `main`. The pull request template asks what changed, how you checked it, and how to reproduce any analysis result. Maintainers review the method, implementation, and evidence before merging.
+
+Use a public or synthetic example when sharing a bug report. Remove account credentials, personal information, and private participant data from logs and screenshots.
+
+## Share a community tutorial
+
+Official usage tutorials are maintained in English. Community tutorials can use
+any language, including Simplified Chinese and Japanese. A written guide, video,
+translated walkthrough, or explanation of a confusing setup step is welcome.
+
+- Submit a link or draft through the [community tutorial form](https://github.com/dengzhe-hou/auto-eeg-analysis/issues/new?template=community-tutorial.md), or open a documentation pull request. You do not need to write code to share a guide.
+- Include the AEA tag or commit, operating system, software and client versions, data source, steps actually tried, and expected outputs. Public or synthetic data make the example easier for others to follow.
+- Credit the original instructions when translating or adapting them. Identify any changes to the analysis settings and explain why they were made.
+- For a guide hosted in this repository, use `docs/community/<descriptive-name>.md`, name its language and author, and link the official English instructions it follows. An external guide can remain on its author's site; share its link and attribution for review.
+
+Maintainers review submitted guides before adding them to the documentation.
+Community guides should identify their author, language, tested version and
+tested scope. A tutorial submission alone does not establish numerical
+certification or support for an entire platform.
+
+## Report a first run or platform check
+
+Use the [first-run and platform feedback form](https://github.com/dengzhe-hou/auto-eeg-analysis/issues/new?template=first-run-platform-feedback.md)
+to share what worked, failed, or was unclear. Reports from macOS users, including
+Intel and Apple Silicon MacBooks, are welcome. You can fill in the form in any
+language, even if you only completed part of the setup.
+
+Record the AEA version, operating system and CPU architecture, relevant Python
+or MATLAB/EEGLAB versions, agent client and model if used, instructions followed,
+and the steps actually exercised. Include the outcome, any manual fixes, and
+shareable logs, screenshots or check results. A model account is unnecessary if
+you only tried the fixed tutorial or saved-result replay.
+
+Distinguish environment setup, client launch, analysis completion, output checks
+and replay in your report. Maintainers can use a reproducible, scoped report to
+update the [platform record](docs/PLATFORM_SUPPORT.md). Successful client launch
+only establishes that launch step; numerical checks need their actual results.
+Keep failed or incomplete steps visible so the instructions can be improved.
+
+## Contribute a recipe
+
+A recipe is a reusable Markdown specification of a published EEG analysis: data requirements, parameters, claims, figures, and references.
+
+1. Fork the repository and create a branch for your change.
+2. Copy [recipes/_template/](recipes/_template/) to `recipes/<your-slug>/`.
+3. Fill in `RECIPE.md` and add `citation.bib`. State the required channels, sampling rate, event mapping, trial counts or clean recording duration, preprocessing, statistics, and expected outputs.
+4. Run the specified analysis on at least one public dataset. Record where to obtain the data, the exact configuration and command, results, and any deviations from the recipe. Place access instructions in `validation/README.md` if needed; do not commit raw participant data.
+5. Add a regression check under `recipes/<your-slug>/tests/` for the key numerical result. The [ERN test](recipes/ern-flankers/tests/test_ern_flankers.py) demonstrates dataset discovery and bounded numerical assertions. Choose tolerances appropriate to your analysis and record their basis.
+6. Run the checks below and open a pull request titled `recipe: <slug>: <short description>`.
+
+Use the recipe template's status vocabulary: `experimental`, `validated`, or `canonical`. Document which dataset and configuration support the status, including unsupported claims or contrasts that have not been tested. Validation of one contrast does not establish every other contrast in the recipe. Keep existing results and limitations visible when adding new evidence.
+
+The [eeg-recipe skill](skills/eeg-recipe/SKILL.md) describes the execution sequence and expected project outputs. In the pull request, include the source citation, data access instructions, changed parameters, validation results, and test summary so someone else can repeat the run.
+
+## Contribute a skill
+
+Skills in `skills/eeg-*/SKILL.md` teach the coding assistant how to perform individual analysis stages. You can add a method, clarify parameters, improve data handling, or fix a supported platform path.
+
+- Keep `SKILL.md` as a compact entrypoint: frontmatter, scope, required inputs, essential rules and links to the relevant procedures. Put detailed templates, constants, phases, outputs and failure modes in `references/procedure.md`; put conditional method explanations in `references/background.md`. Link supporting files from the entrypoint so an agent can discover them without loading every reference. [eeg-erp](skills/eeg-erp/SKILL.md) is an example of a computational stage; [eeg-recipe](skills/eeg-recipe/SKILL.md) composes stages.
+- Keep methodology and analysis contracts in Markdown. A helper specific to one skill can live in its `scripts/` directory; shared tools belong in `tools/`, recipe checks in `recipes/<slug>/tests/`, and backend code templates in [templates/backends/](templates/backends/). Test the executable procedure or helper, rather than matching its wording.
+- Verify selected sections with `python tools/load_skill.py eeg-spectral --section "Phase B — PSD computation"` (substitute the changed skill/section). Check that the packet contains the procedure and names its actual reference file. Loading an entrypoint alone does not demonstrate that the computation template was delivered or followed.
+- Add required Python dependencies to [environment.yml](environment.yml). State optional dependencies and how to detect their absence.
+- For backend changes, update [backends.json](tools/env/backends.json) and the relevant probes in [check_env.sh](tools/env/check_env.sh) and [check_env.ps1](tools/env/check_env.ps1). Keep the capability description aligned with the paths you actually exercised.
+- Test the affected path on public or synthetic data that exercises the change. Record the environment and meaningful numerical expectations when the change affects analysis results.
+
+MNE is the primary execution backend. Existing EEGLAB and FieldTrip paths have specific capabilities, templates, and comparison results; a contribution should state which stage and configuration it implements. See [platform support](docs/PLATFORM_SUPPORT.md) and the [backend templates](templates/backends/README.md).
+
+## Contribute a tool, document, or fix
+
+For usage questions, check [troubleshooting](docs/GETTING_STARTED.md#troubleshooting), then
+open a [GitHub issue](https://github.com/dengzhe-hou/auto-eeg-analysis/issues/new/choose).
+Issues are the public support channel for project questions and reproducible bug reports.
+
+Bug reports are most useful with the command or prompt, traceback, affected skill or recipe, environment details, and a small public or synthetic example. For documentation fixes, link the relevant instructions and explain the step that was confusing or incorrect.
+
+Useful starting points include [tools/env/](tools/env/), [tools/auto_brief.py](tools/auto_brief.py), the [project templates](templates/), and [docs/](docs/). Existing computational skills include decoding, spectral analysis, behavior, connectivity, microstates, source analysis, and BIDS support; check them before proposing a duplicate skill.
+
+## Run the checks
+
+Choose checks that exercise the changed behavior. For code, skills, recipes, or plugin changes, run the relevant tests and record the actual environment. From the repository root, the full suite uses the `aeais` environment described in [Getting started](docs/GETTING_STARTED.md):
+
+```bash
+conda run -n aeais python -m pytest tools/tests/ recipes/
+```
+
+For a recipe with its own test directory, you can first run the focused check:
+
+```bash
+conda run -n aeais python -m pytest recipes/<your-slug>/tests/ -v
+```
+
+The suite includes infrastructure checks, recorded-result checks, and tests that execute an analysis when its dataset is available. Read the pass and skip counts together:
+
+- The MNE sample-data regression tests skip if the sample dataset is absent. Reuse an existing MNE data cache when possible. Setting `AEA_FETCH_DATA=1` explicitly opts into fetching that dataset for the tests.
+- The ERN recipe test looks for a local ERP CORE Flankers file. Set `AEA_ERP_CORE_FLANKERS` to its path, or use the location documented in [the test](recipes/ern-flankers/tests/test_ern_flankers.py). It skips with setup instructions if the data are missing.
+- A skipped data-dependent test is not evidence that the analysis passed. Report required datasets and skips in the pull request. Do not turn computation failures into skips.
+
+[GitHub Actions](.github/workflows/ci.yml) runs the same suite on Ubuntu for pull requests and pushes to `main`. Passing the tests verifies the covered checks; the run record for your new analysis or backend path supplies the additional evidence specific to that contribution.
+
+## Recognition
+
+All contributors are listed in the repo. For the eventual AEA paper (target: Scientific Data, Article), significant contributors (major recipes, major skills, or sustained engagement) will be invited as co-authors. The bar is real contribution, not a single typo fix.
+
+## House rules
+
+- Keep skills and recipes readable as standalone methodology specifications, with the source references and parameters needed to reproduce a run.
+- Record backend selection and substitutions explicitly. Stop with a useful error when a required capability is missing.
+- Verify references against their sources. Include the dataset and configuration behind numerical claims.
+- Preserve the analysis plan, seed settings, numerical baselines, and existing result records when changing a stage. Explain any intentional result change in the pull request.
+
+## License
+
+The repository is distributed under the [MIT License](LICENSE). Existing recipe frontmatter also declares `CC-BY-4.0`; preserve its license and attribution fields when editing a recipe.

auto_eeg_analysis-0.3.3rc1/LICENSE

@@ -0,0 +1,28 @@
+MIT License
+
+Copyright (c) 2026 Dengzhe Hou and AEA contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Note on recipes: each recipe under recipes/<name>/RECIPE.md may carry its own
+license declaration in the YAML frontmatter (typically CC-BY-4.0 to encourage
+reuse). The MIT license above governs the AEA code, skills, templates, and
+tools; recipes follow their own declared licenses.