close docs will be off system for its definitions (global) each app will follow
these guidelines and update/override system for their partical apps in
apps/appname/docs ; .env will start at the system level and be in apps folders
to override different api, db, password, licenses etc used only by that app;
tictoe is really an shortened example ; dashes reminder are not allowed in
filenames! coding rule; we need to make sure the ai agents get this and other
rules right away; test before delivering code, don't assume ask for
confirmations, always have error handling (production quality coding) modular
approach, not object oriented coding but structured coding - object will be
limited i.e. for mysql; coding: bash, macos/linux, php, html, js, bootstrap5,
fontawesome, datatables, mysql to start; awk, py when required

Yes—this changes the documentation model significantly. The global, authoritative documentation belongs under system/docs/, while each application owns an optional apps/<app_name>/docs/ directory for application-specific additions and overrides.

Also, I will follow your project rule: hyphens are not allowed in project
filenames or directory names. For project-owned names, use lowercase
snake_case; keep ecosystem-required conventional names such as README.md,
AGENTS.md, .env, and .gitignore.


1. Root AGENTS.md:
   Mandatory rules for every repository and every application.

2. system/docs/:
   Global system definitions, coding standards, architecture, deployment,
   security, testing, configuration, and operating rules.

3. apps/<app_name>/AGENTS.md:
   App-specific coding instructions and constraints.
   It may add rules, but cannot weaken root safety or quality rules.

4. apps/<app_name>/docs/:
   App-specific documentation.
   It may override a system default only where the app requires a documented
   different behavior, configuration, integration, database, API, or license.

# Configuration Override

This application uses the global configuration rules in
`system/docs/configuration.md`.

## Application Overrides

- Uses a separate database connection defined in this application's `.env`.
- Uses an application-specific API key.
- Uses an application-specific license value.
- Uses an application-specific log directory.

Global system .env
        ↓
Application .env
        ↓
Application-specific runtime values

PRACTICAL RULE
- The root or system .env defines shared paths and shared defaults.
- Each application .env defines only values that differ for that application.
- Application .env values override matching system values.
- PHP and Bash must load configuration in a deterministic, documented order.
- Never hard-code filesystem paths, passwords, API keys, database credentials,
  license keys, or environment-specific URLs in PHP, Bash, JavaScript, SQL,
  or documentation.
- Commit .env.example files, never real .env files.

Mandatory agent rules
Place this concise policy in the root AGENTS.md. This is the file AI coding tools should encounter first.
# AI Agent Rules

## Read First

Before changing code, read:

1. `AGENTS.md`
2. `system/docs/README.md`
3. The applicable document in `system/docs/`
4. The nearest application `AGENTS.md`, if working in `apps/`
5. The applicable application documentation in `apps/<app_name>/docs/`

Application rules may add requirements but may not weaken root requirements.

## File Naming

- Do not use hyphens in project-created file or directory names.
- Use lowercase `snake_case` for project-created names.
- Do not use spaces, tildes, or special characters in names.
- Preserve required ecosystem names exactly, including:
  `.env`, `.gitignore`, `README.md`, `AGENTS.md`, `LICENSE.md`,
  `SECURITY.md`, and `.github`.

## Technology Scope

Use these technologies unless the task explicitly changes the scope:

- Bash for macOS and Linux automation.
- PHP for server-side application code.
- HTML, JavaScript, Bootstrap 5, Font Awesome, and DataTables for UI work.
- MySQL for database storage.
- AWK or Python only when they are the appropriate tool for the task.

Do not introduce Node.js, npm, Composer, Docker, frameworks, packages,
or new external dependencies without explicit approval.

## Code Quality

- Write production-quality code.
- Use a modular, structured programming approach.
- Do not introduce object-oriented architecture by default.
- Limit objects to cases where they provide clear value, such as MySQL/PDO use.
- Keep functions focused and reusable.
- Separate configuration, data access, business logic, output, and UI behavior.
- Avoid duplicated logic and hard-coded values.
- Use clear names and comments only where they add necessary context.

## Error Handling

- Every external operation must have error handling.
- Validate all input before processing it.
- Check filesystem, database, command, network, and API failures.
- Return or display useful errors without exposing secrets or internals.
- Log actionable diagnostic details where logging is available.
- Use safe defaults and fail closed for authorization, permissions, and secrets.

## Change Procedure

- Do not assume unclear requirements.
- Ask for clarification before choosing behavior, architecture, naming,
  permissions, data retention, destructive actions, or external side effects.
- Inspect relevant code and documentation before modifying files.
- Preserve backward compatibility unless a breaking change is explicitly approved.
- Update applicable system or application documentation with code changes.
- Do not claim code is tested unless tests were actually run.

## Testing Before Delivery

Before delivering code:

1. Run relevant syntax checks.
2. Run applicable unit, integration, shell, or manual tests.
3. Test error paths, not only successful paths.
4. Verify configuration loading and path resolution where relevant.
5. Report exactly what was tested and the result.
6. If testing cannot be performed, state why and identify the unverified risk.

## Git

- The designated master repository is the canonical single source of truth.
- Do not manually synchronize repositories by copying source files.
- Review `git status` before and after changes.
- Do not commit `.env`, logs, caches, generated files, credentials, or secrets.
- Make focused commits with clear messages.