#!/usr/bin/env bash

# 1. CREATE UNIFIED AGENTS.md (Single Source of Truth)
cat << 'INNER_EOF' > AGENTS.md
# AGENTS.md

> **Attention Humans & AI Agents:** This file is the project's single source of truth for file naming, code standards, and folder layouts. All modifications must strictly adhere to these rules.

## 1. File Naming Rules (Strict)
* **All Lowercase**: No capital letters are permitted in any filename.
* **No Separators**: Do not use dashes (`-`), underscores (`_`), or double underscores (`__`).
* **Dot Separation**: Use dots (`.`) to separate logical parts of the filename. 
* **Extension Placement**: The final dot must immediately precede the file extension.
* **Allowed Extensions**: `.php`, `.js`, `.json`, `.css`, `.md`

### Examples
* ✅ **Good**: `admin.tool.php`, `app.config.json`, `main.js`, `style.css`
* ❌ **Bad**: `admin_tool.php`, `admin-tool.php`, `Admin.Tool.php`, `bootstrap__core.php`

---

## 2. Code Naming Rules (PHP, JS, HTML)
* **Functions & Variables**: Must use strict `camelCase`. Do not use dots, dashes, or underscores.
  * ✅ **Good**: `sysPath()`, `appUrl()`, `$appId`, `$systemRoot`
  * ❌ **Bad**: `sys_path()`, `sys-path()`, `$app_id`, `$app.id`
* **Constants**: Eliminate language-native uppercase constants to avoid underscores. Use system-wide `camelCase` variables instead.
  * ✅ **Good**: `systemRoot`
  * ❌ **Bad**: `SYSTEM_ROOT`
* **No Custom Double Underscores**: Do not use `__` anywhere in filenames or custom code identifiers. (Language-native magic constants like PHP's `__FILE__` are the only exception).

---

## 3. Directory Layout & App IDs

### Structure Rules
* **App IDs**: Formatted using dots following a `category.name` pattern (e.g., `apps.appdefault`).
* **Path Mapping**: App IDs mirror physical directory layouts under the local directory architecture.
* **Registry Rule**: The application registry maps IDs to paths. To rename an app, **modify the registry configuration only**. Never rename the physical files/folders manually.

### Repository Tree Structure
```text
.
├── AGENTS.md                  <-- This file (Root single source of truth)
├── apps/                      <-- Application collection root
│   ├── sh/                    <-- Global shell scripts
│   └── appdefault/            <-- Default application profile (Maps to apps.appdefault)
│       ├── admin/
│       ├── ai/
│       │   ├── output/
│       │   └── prompts/
│       ├── audit/
│       ├── config/
│       ├── css/
│       │   └── themes/
│       ├── data/
│       │   ├── config/
│       │   ├── fonts/
│       │   ├── logs/
│       │   └── sql/
│       ├── docs/
│       ├── img/
│       ├── js/
│       ├── pages/
│       ├── php/
│       ├── scripts/
│       ├── sql/
│       ├── src/
│       ├── templates/
│       └── tests/
├── docs/                      <-- Global system documentation
├── review/                    <-- Code review sandbox
└── system/                    <-- System engine core config and tools
    ├── admin/
    ├── ai/
    │   ├── output/
    │   └── prompts/
    ├── audit/
    ├── core/                  <-- Engine core code
    ├── css/
    │   └── themes/
    ├── data/
    │   ├── config/
    │   ├── fonts/
    │   └── sql/
    ├── docs/
    ├── img/
    ├── js/
    ├── pages/
    ├── php/
    ├── scripts/
    ├── sh/
    ├── sql/
    ├── templates/
    └── tests/
```

---

## 4. System Exceptions
* **Single-Word Entrypoints**: `index.php` is allowed without dot separation.
* **Documentation**: Files like `readme.md` or `changelog.md` are valid if completely lowercase.
* **Server Overrides**: System files like `.htaccess` are allowed but should be minimized.
INNER_EOF

# 2. CREATE README.md (Focussed Portal)
cat << 'INNER_EOF' > README.md
# Application System Engine

Welcome to the development environment repository. This workspace contains core modules, shared assets, automation workflows, and specific isolated applications.

## 🛠 Project Standards & AI Context
To ensure high maintainability, strict naming patterns apply to every single file, path, function, and variable inside this workspace. 

* **Coding & Naming Blueprint**: Both human developers and automated AI tools must read, reference, and prioritize the rules stored inside [AGENTS.md](./AGENTS.md). Do not write raw code configurations outside those boundaries.
* **System Directory Mapping**: The full map of authorized system structures, including core spaces, sandboxes, and application default configurations, is strictly maintained within [AGENTS.md](./AGENTS.md#3-directory-layout--app-ids).

## 🚀 Workspace Layout Summary
* `apps/`: Host location for operational services and scripts.
* `system/`: Global codebase backbone containing shared templates, routing systems, testing setups, and configuration states.
* `review/`: Protected sandboxed environment for ongoing validation logic.
* `docs/`: Technical records.

For complete instruction profiles regarding local builds, registry alterations, and strict lowercase structural setups, consult the project's centralized guideline matrix.
INNER_EOF

# 3. CREATE CONTRIBUTING.md (Developer Gateway)
cat << 'INNER_EOF' > CONTRIBUTING.md
# Contributing Guidelines

Thank you for dedicating development time to this codebase. To keep continuous integration simple and fully prevent syntax breaks across our registry, all pull requests must conform to our uniform automation architecture.

## 📜 Strict Architectural Rules
This repository enforces an exact, non-negotiable coding and structural pattern to prevent parsing failures across PHP, JS, and JSON layers:

1. **File Conventions**: No capitalized paths, dashes, or structural underscores. Files follow strict dot-separation definitions.
2. **Code Syntax Rules**: Functional calls and assigned values use `camelCase` exclusively. Native UPPERCASE underscores are restricted.
3. **Registry Enforcement**: Paths represent explicit Application Identifiers. Under no circumstance should a physical workspace path be renamed outside configuration states.

## 🎯 Single Source of Truth
We enforce a unified document blueprint to avoid version drift between developer habits and automated AI generation layers. 

Before committing lines, adding a feature, or structuring a script inside `apps/` or `system/`, you must thoroughly inspect and replicate the precise conventions written directly inside **[AGENTS.md](./AGENTS.md)**. 

If any code patterns or module pathways violate the layout defined within the unified instruction file, the associated submission will fail continuous integration validation workflows.
INNER_EOF
 4. EXPLICIT SYMLINK FOR CLI AGENTS
#ln -sf AGENTS.md CLAUDE.md

echo "✅ Success: AGENTS.md, README.md, and CONTRIBUTING.md have been explicitly populated and synchronized!"