added unity files

docs/AUTOMATION.md

@@ -1,108 +1,113 @@
 # Automation
 
-## Purpose
+## Intentional Behavior
 
-This repository includes two Forgejo Actions workflows for reusable customer-project automation:
+This repository is for customer debugging projects.
 
-- `validate.yml`: runs repository validation on push and pull request.
-- `project-report.yml`: generates best-effort project analysis reports on push and pull request.
+Customers are expected to upload broken code.
+
+Because of that:
+
+- Green workflow means automation completed.
+- Red workflow means automation failed.
+- Customer code errors are listed in `reports/errors.md`.
+- Broken customer code does not fail the workflow red.
+
+This behavior is intentional for DevPlus1.
 
 ## Workflows
 
 ### `validate.yml`
 
-- runs on `push`
-- runs on `pull_request`
-- uses the `linux-dev` runner label
-- checks out the repository
-- runs `tools/validate-code.sh`
-- fails when validation finds real errors
+- Runs on `push`
+- Runs on `pull_request`
+- Uses runner label `linux-dev`
+- Runs `tools/validate-code.sh`
+- Prints `reports/errors.md` into Forgejo logs
+- Fails only if the validation script crashes or `reports/errors.md` is missing
 
 ### `project-report.yml`
 
-- runs on `push`
-- runs on `pull_request`
-- uses the `linux-dev` runner label
-- checks out the repository
-- runs `tools/project-report.sh`
-- regenerates reports in `reports/`
-- does not fail because analysis finds issues or uncertainty
-- only fails if the script itself crashes
+- Runs on `push`
+- Runs on `pull_request`
+- Uses runner label `linux-dev`
+- Runs `tools/validate-code.sh`
+- Runs `tools/project-report.sh`
+- Prints report summaries into Forgejo logs
+- Fails only if report generation crashes or required report files are missing
+
+### `code-docs.yml`
+
+- Runs on `push`
+- Runs on `pull_request`
+- Uses runner label `linux-dev`
+- Runs `tools/generate-code-docs.sh`
+- Prints code documentation summary output into Forgejo logs
+- Fails only if the documentation script crashes or required code documentation reports are missing
 
 ## Scripts
 
 ### `tools/validate-code.sh`
 
-This script recursively scans the repository while excluding common generated or dependency folders such as:
-
-- `.git`
-- `.forgejo`
-- `node_modules`
-- `vendor`
-- `Library`
-- `Temp`
-- `Logs`
-- `obj`
-- `bin`
-
-When the necessary tools are installed, it validates:
-
-- PHP with `php -l`
-- Python with `python3 -m py_compile`
-- Ruby with `ruby -c`
-- Perl with `perl -c`
-- Shell with `bash -n`
-- JavaScript with `node --check`
-- JSON with `jq`
-- YAML with `yamllint`
-- HTML with `tidy`
-- C# with `dotnet build`
-- C/C++ CMake projects with `cmake` configure validation
-
-It writes `reports/errors.md` with:
-
-- validation summary
-- files checked
-- warnings
-- errors
-- detailed per-file results
+- Recursively scans the repository
+- Excludes common dependency and generated directories
+- Validates supported files when tools are installed
+- Always writes `reports/errors.md`
+- Always prints a terminal summary
+- Exits `0` even when customer code errors are found
+- Exits non-zero only for automation/report generation failure
 
 ### `tools/project-report.sh`
 
-This script generates:
+- Generates project analysis reports
+- Reads customer code error status when available
+- Writes summary and generated-file tracking reports
+- Exits non-zero only if the script itself cannot generate required outputs
 
+### `tools/generate-code-docs.sh`
+
+- Reads customer source files without modifying them
+- Generates best-effort API, file-purpose, Unity lifecycle, and call-map reports
+- Uses regex-based extraction and cautious wording
+- Exits non-zero only if report generation fails
+
+## Generated Report Files
+
+- `reports/errors.md`
 - `reports/project-flow.md`
 - `reports/file-summary.md`
 - `reports/languages.md`
+- `reports/summary.md`
+- `reports/generated-files.md`
+- `reports/customer-code-status.txt`
+- `reports/api-reference.md`
+- `reports/file-purpose.md`
+- `reports/unity-scripts.md`
+- `reports/call-map.md`
+- `reports/code-docs-summary.md`
 
-It performs best-effort analysis for:
+## Validation Sample Files
 
-- language counts
-- likely entry points
-- possible startup files
-- framework detection
-- database detection
-- environment files
-- config files
-- Docker-related files
-- probable application flow
+The repository includes intentional validator fixtures under `tests/validation-samples/`.
 
-The wording is intentionally cautious. It does not claim certainty.
+These files exist to prove:
 
-## Reuse In Future Customer Repositories
+- valid samples are accepted
+- broken samples are reported
+- broken customer code does not force the workflow red
 
-To reuse this automation in another repository:
+## Extending The System
 
-1. Copy `.forgejo/workflows/validate.yml`
-2. Copy `.forgejo/workflows/project-report.yml`
-3. Copy `tools/validate-code.sh`
-4. Copy `tools/project-report.sh`
-5. Create `reports/.gitkeep`
-6. Keep the exclude list if the repository includes generated or dependency folders
-7. Review language and framework detection rules for project-specific needs
+To add more validators later:
 
-## Notes
+1. Update `tools/validate-code.sh`
+2. Document the validator in `docs/VALIDATORS.md`
+3. Update `docs/AUTOMATION.md` and `docs/WORKFLOWS.md` if workflow behavior changes
+4. Update `docs/CODEX_INSTRUCTIONS.md`
 
-- Reports are regenerated on every run.
-- Validation skips checks gracefully when required tools are not installed.
-- The automation is additive and does not modify customer source files.
+To add more code documentation extraction later:
+
+1. Update `tools/generate-code-docs.sh`
+2. Document new reports in `docs/REPORTS.md`
+3. Document workflow changes in `docs/WORKFLOWS.md`
+4. Update `docs/CODEX_INSTRUCTIONS.md`