update

Author: denisecase

AGENTS.md

@@ -1,4 +1,4 @@
-# ./AGENTS.md
+# ./AGENTS.md (SE Admin)
 
 ## Scope
 
@@ -58,3 +58,18 @@ uv run python -m zensical build
 
 - pre-commit runs only on tracked / staged files.
 - Developers should `git add -A` files before expecting hooks to run.
+
+
+## SE Admin CLI
+
+All admin operations run through the CLI. Use `--dry-run` before any mutating command.
+
+```shell
+uv run python -m se_admin repos
+uv run python -m se_admin tasks
+uv run python -m se_admin check --set foundation
+uv run python -m se_admin run  --dry-run
+uv run python -m se_admin run
+```
+
+Task files live in `data/tasks/`. Filename must match `[task].id`.

CHANGELOG.md

@@ -1,5 +1,7 @@
 # Changelog
 
+<!-- markdownlint-disable MD024 -->
+
 All notable changes to this project will be documented in this file.
 
 The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/)**
@@ -9,6 +11,53 @@ and this project adheres to **[Semantic Versioning](https://semver.org/spec/v2.0
 
 ---
 
+## [0.1.1] - 2026-04-29
+
+### Added
+
+- Data-driven DSL architecture: declarative TOML task files interpreted by
+  a composable operation tree (`AtomicOperation | OpSequence | Conditional`)
+- Domain layer: `repos`, `profiles`, `selectors`, `tasks`, `findings`,
+  `operations`, `capabilities`
+- Observe layer: `filesystem`, `toml_files`, `pyproject`, `workflows`,
+  `git`, `github` - actual repo state, no decisions
+- Actions layer: `copy_file`, `replace_file`, `patch_toml`,
+  `patch_markdown`, `run_command` - primitive idempotent mutations
+- Checks layer: `required_paths`, `exact_files`, `workflows`,
+  `python_version`, `reference_files`, `tags` - pure comparisons
+  returning `Finding` objects
+- Migrations layer: `replace_mkdocs_with_zensical`, `python_package_profile`,
+  `python_tooling_profile`, `python_version`, `workflow_names` -
+  composed action sequences
+- Reports layer: `summary` (terminal), `markdown` (docs/CI),
+  `json_report` (machine-readable)
+- CLI commands: `show`, `repos`, `tasks`, `check`, `run`
+- `check` command: profile checks against a single repo or repo set,
+  exits 1 on any failure
+- `run` command: execute a task by id with `--dry-run` support
+- Profile `extends` - profiles can reference other profiles;
+  `all_repos` baseline profile composes `markdown` + `links`
+- `all_repos` added as first profile on all repo entries, replacing
+  explicit `links` declarations
+- `profiles.toml`: structured by language/toolchain then docs generator
+  then cross-cutting; `html_static`, `markdown`, `all_repos` profiles added
+- `repos.toml`: all repos updated to use `all_repos` baseline
+- Task files: `normalize_core_files`, `normalize_lychee_location` label
+  fields added; friendly error on missing `[task].label`
+- `utils/paths.py`, `utils/text.py` - path resolution and text formatting
+  utilities
+- Tests: `test_config_loader`, `test_profiles`, `test_required_paths`,
+  `test_reports`
+- Docs: `concepts.md`, `commands.md`, `configuration.md`, `examples.md`
+
+### Fixed
+
+- `domain/operations.py` forward reference resolved with
+  `from __future__ import annotations`
+- Ruff suppressions: `S603`, `S607` (subprocess), `S310` (urlopen)
+
+---
+
 ## [0.1.0] - 2026-04-22
 
 ### Added
@@ -49,5 +98,6 @@ git tag v0.1.0 -m "0.1.0"
 git push origin v0.1.0
 ```
 
-[Unreleased]: https://github.com/structural-explainability/se-admin/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/structural-explainability/se-admin/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/structural-explainability/se-admin/releases/tag/v0.1.1
 [0.1.0]: https://github.com/structural-explainability/se-admin/releases/tag/v0.1.0

CITATION.cff

@@ -9,8 +9,8 @@ cff-version: "1.2.0"
 type: software
 
 title: "Structural Explainability Admin"
-version: "0.1.0"
-date-released: "2026-04-22"
+version: "0.1.1"
+date-released: "2026-04-29"
 
 authors:
   - family-names: Case

README.md

@@ -12,6 +12,11 @@
 > Structural Explainability Admin:
 > administration of the SE ecosystem.
 
+SE Admin is a data-driven system that applies composable operations
+over repository surfaces
+with declarative targets and selectable scope
+to move repos between states.
+
 ## Owns
 
 - enforcement of constitution (automation)
@@ -41,19 +46,131 @@ bulk operations
 - dependency upgrades
 - structural updates
 
+## Overview
+
+```text
+data/       = declared desired state, no logic, only declarations
+observe/    = actual repo state, no decisions, only facts
+checks/     = pure comparison, no side effects
+actions/    = primitive mutations
+migrations/ = composed actions
+reports/    = human/machine output projections only
+```
+
+```text
+domain/
+  repo        - repository
+  profile     = named bundle of expectations (paths, workflows, checks)
+  selector    = how you choose repos (set, name, pattern)
+  finding     = result of a check
+```
+
+```text
+repos.toml       = instances: which repos exist, repo sets, assigned profiles
+profiles.toml    = reusable traits: profile definitions
+checks.toml      = constraints: check definitions and canonical comparisons
+migrations.toml  = transformations: named migration recipes
+```
+
+```text
+data (declared) -> observe (actual) -> checks (compare) -> actions/migrations -> reports
+```
+
+## Operation Requirements
+
+Data describes operations and a small interpreter executing them
+
+All operations must be:
+
+- deterministic
+- idempotent
+- side-effect scoped
+
+Examples:
+
+- delete_file is OK if missing
+- add_dependency is OK if already present
+- replace_text is no-op if not found
+
+## Operation Taxonomy
+
+### Detection (no side effects)
+
+- path_exists
+- path_missing
+- toml_key_exists
+- toml_value_equals
+- dependency_present
+- workflow_present
+
+### Mutation (single responsibility)
+
+Filesystem
+
+- create_file
+- delete_file
+- copy_file
+- ensure_directory
+- rename_path
+  TOML
+- toml_set_key
+- toml_remove_key
+- toml_add_dependency
+- toml_remove_dependency
+- toml_ensure_table
+  Workflows (still files, but special intent)
+- ensure_workflow
+- remove_workflow
+- replace_workflow
+  Text
+- replace_block
+- insert_block
+- remove_block
+  Process
+- run_command
+
+## Composition
+
+```text
+Operation =
+  AtomicOperation
+  | Sequence[Operation]
+  | Conditional(condition, Operation)
+```
+
+## Example
+
+A tool transition is a declarative description of how to
+remove one capability and establish another across all affected surfaces.
+
+```text
+Sequence(
+  Conditional(detect_mkdocs, Sequence(
+    delete_file("mkdocs.yml"),
+    toml_remove_dependency("mkdocs"),
+    remove_workflow("deploy-mkdocs.yml")
+  )),
+
+  Sequence(
+    create_file("zensical.toml"),
+    toml_add_dependency(group="docs", name="zensical"),
+    ensure_workflow("deploy-zensical.yml"),
+    ensure_directory("docs")
+  )
+)
+```
+
 ## Command Reference
 
 <details>
 <summary>Show command reference</summary>
 
 ### In a machine terminal
 
-After you get a copy of this repo in your own GitHub account,
-open a machine terminal in `Repos` or where you want the project:
+Open a machine terminal where you want the project:
 
 ```shell
-# Replace username with YOUR GitHub username.
-git clone https://github.com/username/se-admin
+git clone https://github.com/structural-explainability/se-admin
 
 cd se-admin
 code .

SE_MANIFEST.toml

@@ -11,7 +11,7 @@ schema = "se-manifest-2"
 name = "se-admin"
 org = "structural-explainability"
 status = "active"
-version = "0.1.0"
+version = "0.1.1"
 
 [repo]
 # WHY: Repo identity is defined structurally
@@ -50,7 +50,7 @@ excludes = [
 ]
 
 [validation]
-entrypoint = "se_admin.app:run_show"
+entrypoint = "se_admin.cli:main"
 
 # === Behavior / governance ===
 

data/checks.toml

@@ -0,0 +1,91 @@
+# data/profiles.toml
+
+# repos.toml = which repos exist and which profiles they compose
+# profiles.toml = what each profile requires
+
+# === ALL REPOSITORIES ===
+
+[profiles.all_repos]
+label = "Baseline for all repositories"
+description = "Every repository in the ecosystem must satisfy this profile."
+extends = ["markdown", "links"]
+
+# === GO REPOSITORIES ===
+
+# === HTML/CSS/JS REPOSITORIES ===
+
+[profiles.html_static]
+label = "Static HTML documentation repository"
+description = "Repository serving pre-authored HTML, no build step."
+required_paths = ["docs/index.html"]
+
+# === LATEX PAPER REPOSITORIES ===
+
+[profiles.paper_latex]
+label = "LaTeX paper repository"
+description = "Repository containing a LaTeX paper source."
+required_paths = ["README.md", "LICENSE"]
+optional_paths = ["main.tex", "paper.tex", "references.bib", "latexmkrc"]
+
+
+# === LEAN THEOREM PROVING REPOSITORIES ===
+
+[profiles.lean]
+label = "Lean repository"
+description = "Repository containing Lean formalization artifacts."
+required_paths = ["lean-toolchain", "lakefile.toml"]
+required_workflows = ["ci-lean.yml"]
+
+# == MARKDOWN REPOSITORIES ===
+
+[profiles.markdown]
+label = "Markdown repository"
+description = "Repository containing Markdown documentation."
+required_paths = [".markdownlint.yml","README.md"]
+
+# === PYTHON SRC REPOSITORIES ===
+
+[profiles.python_package]
+label = "Python package repository"
+description = "Repository containing a Python package with source layout."
+required_paths = ["pyproject.toml", "src", "tests"]
+required_workflows = ["ci-python-zensical.yml"]
+
+# === PYTHON FOR TOOLING ONLY REPOSITORIES ===
+
+[profiles.python_tooling]
+label = "Python tooling repository"
+description = "Repository using Python for repository tooling, documentation, or automation without a package contract."
+required_paths = ["pyproject.toml"]
+required_workflows = ["ci-python-zensical-tooling.yml"]
+
+# === PYTHON ZENSICAL REPOSITORIES ===
+
+[profiles.zensical]
+# this repo has docs built by Zensical using Python
+# therefore pyproject.toml must include Zensical in docs dependencies
+label = "Zensical documentation repository"
+description = "Repository that builds documentation with Zensical."
+required_paths = ["zensical.toml", "docs"]
+required_workflows = ["deploy-zensical.yml"]
+
+[profiles.zensical.pyproject]
+required_optional_dependency_groups = ["docs"]
+
+[profiles.zensical.pyproject.optional_dependencies.docs]
+required = ["zensical"]
+
+# === REPOSITORIES WITH LINK CHECKING ===
+
+
+[profiles.links]
+label = "Link-checked repository"
+description = "Repository checked with the standard link-checking workflow."
+required_workflows = ["links.yml"]
+
+# === REPOSITORIES WITH REFERENCE ARTIFACTS ===
+
+[profiles.reference]
+label = "Reference artifact repository"
+description = "Repository containing canonical reference or specification artifacts."
+required_paths = ["reference"]