= {Project Name}
:project-name: {Project Name}
:project-description: {One-line description in UK-British Oxford English}
:language: {Primary language, e.g. Ada 2022, Elixir, Rust}
:version: {Version}
:license: MIT & Palimpsest v0.8
:repo-url: {Repository URL – *REMINDER: Provide this for each project*}
:build-tool: {e.g. Justfile, GPRbuild, Mix, Cargo – *REMINDER: Specify for each project*}

== 🌟 {project-name}
{project-description}

{project-name} is a {language}-based tool that addresses {core problem, e.g. "the challenge of managing overwhelming directory trees in large projects"}. Built with {language}, it provides {key benefits, e.g. "compile-time safety, advanced filtering, and clean, readable output"} through {unique approach, e.g. "SHAKE256(M, d) = KECCAK[512] hashing and type-safe navigation"}.

== 🎯 Why {project-name}?

=== The Problem
{Describe the core problem in 2–3 bullet points, e.g.:

- Standard tree commands produce thousands of lines for modern projects (e.g. Rust's `target/`, Node.js's `node_modules/`).
- No easy way to filter by file type, permissions, or attributes.
- Build artefacts and dependencies clutter the view, obscuring important files.}

=== The Solution
{project-name} offers {key solutions, e.g.:

- Surgical control over directory traversal and output.
- Type-based filtering for executables, configs, scripts, and data files.
- Graceful handling of permission errors and hidden files.}

== ✨ Features

=== Core Capabilities
- {Feature 1, e.g. "Advanced filtering by directory/file patterns"}
- {Feature 2, e.g. "Type-based selection (executables, configs, scripts, data)"}
- {Feature 3, e.g. "Automatic statistics: file counts, sizes, and exclusion metrics"}
- {Feature 4, e.g. "Clean export to files for documentation or analysis"}

=== File Type Detection
{project-name} automatically categorises files, including:

- 📁 Directories
- ⚙️ Executables (`.exe`, `.bin`, or executable permissions)
- ⚙️ System configs (`.conf`, `.cfg`)
- 📜 Shell scripts (`.sh`, `.bash`)
- 📄 Data files (`.json`, `.xml`, `.yaml`, `.yml`)
- 👻 Hidden files (dotfiles)
- 📄 Regular files

*REMINDER: Customise file type categories to match the project's focus.*

== 🚀 Quick Start

=== Prerequisites
- {Dependency 1, e.g. "GNAT Ada Compiler (GCC 12.0+)"}
- {Dependency 2, e.g. "Just command runner"}
- *REMINDER: Replace with actual dependencies for each project.*

=== Installation
[source,bash]
----
# Clone the repository
git clone {repo-url}
cd {project-name}

# Build – *REMINDER: Replace with project-specific command*
just build
# Or for Ada projects:
# gprbuild -P {project-name}.gpr
# Or for Elixir projects:
# mix deps.get && mix compile

# Install (optional) – *REMINDER: Replace with actual install command*
just install
# Or:
# sudo cp bin/{project-name} /usr/local/bin/
----

== 📖 Usage

=== {Primary Use Case}
{Example command and description}

[source,bash]
----
# Example usage – *REMINDER: Provide real-world example*
{project-name} --option value
----

=== {Secondary Use Case}
{Example command and description}

[source,bash]
----
# Example usage – *REMINDER: Provide real-world example*
{project-name} --another-option value
----

=== Real-World Examples
- **Rust project documentation**: {Specific use case}
- **Node.js project analysis**: {Specific use case}
- **Configuration audit**: {Specific use case}

*REMINDER: Replace with actual use cases relevant to the project.*

== 📋 Command-Line Reference

=== General Options
- `-h, --help`: Show help message
- `-v, --version`: Show version information

=== {Feature}-Specific Options
*REMINDER: List actual CLI flags (e.g. `--exclude-dirs`, `--only-type`).*

- `--{option}`: {Description}
- `--{option}`: {Description}

== 🎨 Output Format
*REMINDER: Replace with an example of the project's actual output format.*

[source]
----
Directory tree: /path/to/project
Generated: {date}
📁 project/
├── 📁 src/
│   ├── 📄 main.{language-ext}
│   └── 📄 config.{language-ext}
└── ⚙️ Makefile

Statistics:
Directories:  2
Files:        5
Total size:   45231 bytes
----

== 🏗️ Project Structure
*REMINDER: Update directory tree to reflect actual structure for each project.*
*Examples: `src/`, `lib/`, `priv/` for Elixir; `obj/`, `bin/` for Ada*

[source]
----
{project-name}/
├── src/                  # {Description}
├── bin/                  # {Description}
├── justfile              # Build recipes and common tasks
├── {file}                # {Description}
└── {file}                # {Description}
----

== 🔧 Development

=== Building from Source
[source,bash]
----
# Clean build – *REMINDER: Replace with actual commands*
just clean
just build

# For Ada projects:
# gprclean -P {project-name}.gpr
# gprbuild -P {project-name}.gpr

# For Elixir projects:
# mix clean
# mix compile
----

=== Running Tests
[source,bash]
----
# Run test suite – *REMINDER: Replace with actual test commands*
just test

# For Ada projects:
# gprbuild -P {project-name}_test.gpr
# ./bin/{project-name}_test

# For Elixir projects:
# mix test
----

=== Rigorous Verification and Testing
This project is committed to rigorous verification and testing practices. Documentation specific to testing strategies, formal verification methods, and quality assurance processes can be found in the repository-specific testing documentation.

*Note: This is an ongoing area of development. Proper verification and testing infrastructure is actively being improved.*

== ⚙️ Configuration
*REMINDER: Replace `~/.config/{project-name}/` with actual configuration paths.*

Configuration files are stored in:

- Main config: `~/.config/{project-name}/config.{ext}`
- User preferences: `~/.config/{project-name}/preferences.{ext}`
- {Other config locations as applicable}

== 🛠️ Contributing to the Ecosystem

We use the *Tri-Perimeter Contribution Framework (TPCF)* to balance architectural integrity with community involvement. Each perimeter defines access, responsibilities, and contribution pathways.

=== 🔒 Perimeter 1: Core Systems (Maintainers Only)

**Languages**: Rust, Nickel, Bash, C++

**Responsibilities**:

- Shell runtime (`osh/`, `core/`, `cpp/`)
- Build orchestration (Justfile, Ninja emitters)
- Protocol emitters (`.well-known/*.json`)
- SPDX audit, licence layering, AI boundary declarations
- CI/CD pipelines and containerisation

**Access**: Maintainers only

**Contribution Path**: Closed to public. Maintainers commit directly with full SPDX and compliance coverage.

=== 🧠 Perimeter 2: Expert Extensions

**Languages**: Rust, Nickel, Bash, controlled Python

**Responsibilities**:

- Protocol extensions (e.g. consent tokens, provenance chains)
- Shell plugins (e.g. custom builtins, audit hooks)
- Contributor onboarding flows and documentation tooling
- Compliance validators and synchronisation strategies

**Access**: Trusted contributors

**Contribution Path**:

1. Apply via issue template (`.gitlab/ISSUE_TEMPLATE/expert-contributor.yml`)
2. Submit merge requests under `extensions/` or `emit/`
3. Include:
   - Unit tests
   - Documentation
   - Example usage
   - SPDX headers and licence declaration
4. Reviewed by core maintainers before merge

=== 🌱 Perimeter 3: Community Sandbox

**Languages**: Shell, Markdown, AsciiDoc, JSON

**Responsibilities**:

- Documentation improvements (`doc/`)
- Spec tests (`spec/`, `test/`)
- Compliance manifest proposals (`.well-known/`)
- Contributor guides, onboarding scripts

**Access**: Open to all

**Contribution Path**:

1. Fork the repository
2. Add your contribution under:
   - `doc/` for documentation
   - `spec/` for shell behaviour tests
   - `.well-known/` for protocol suggestions
3. Run `just validate` locally
4. Submit a merge request
5. CI will validate SPDX headers, schema compliance, and formatting

=== 🔁 Lifecycle & Automation

- **CI/CD**: All contributions tested automatically
- **SPDX Audit**: Enforced via `just audit-license`
- **Boundary Declarations**: Synchronised from palimpsest-shell
- **Versioning**: Protocols and APIs are versioned; deprecated features flagged before removal

=== 📐 Coding Conventions

We optimise for clarity and auditability:

- Indent with 2 spaces (except Rust: 4 spaces)
- Use SPDX headers in all source files
- Prefer AsciiDoc over Markdown for structured documentation
- All commits must be atomic (one feature or fix per commit)
- All merge requests must include:
  * SPDX headers
  * Licence declaration
  * Contributor scope (Perimeter 1/2/3)

=== 🤝 Code of Conduct

All contributors must follow our link:CODE_OF_CONDUCT.adoc[Code of Conduct]. Respect boundaries, attribution, and ethical standards.

== 📝 Licence

This project is dual-licensed under:

- **MIT Licence** – For permissive open-source use
- **Palimpsest Licence v0.8** – For ethical AI training and derivative works

You may choose either licence, or both, for your use case.

image:https://img.shields.io/badge/Licence-MIT-yellow.svg[MIT Licence,link=https://opensource.org/licenses/MIT]
image:https://img.shields.io/badge/Licence-Palimpsest_v0.8-blue[Palimpsest Licence,link=https://github.com/hyperpolymath/palimpsest-license]

=== MIT Licence

For individuals and organisations that prefer traditional permissive licensing, this project is available under the MIT Licence.

See link:LICENSE-MIT[LICENSE-MIT] for full terms.

=== Palimpsest Licence v0.8

For those concerned with ethical AI practices and attribution in the age of large language models, this project is also available under the Palimpsest Licence. This licence ensures:

- **Attribution preservation** through derivative works and AI training
- **Contextual integrity** for code used in training data
- **Human authorship** remains traceable even after AI transformation
- **Reciprocal transparency** for AI systems trained on this work

See link:LICENSE-PALIMPSEST[LICENSE-PALIMPSEST] for full terms.

=== Quick Reference

[cols="1,2,2"]
|===
| Use Case                          | Recommended Licence | Why

| Building applications             | MIT                 | Maximum flexibility, no special requirements
| Ethics and AI training            | Palimpsest          | Ensures attribution and ethical use
| Creating derivatives              | Either              | MIT for simplicity, Palimpsest for attribution
| Commercial use                    | Either              | Both licences permit commercial use
| Redistribution                    | Either              | Both require licence inclusion
|===

=== Choosing a Licence

When using this project:

1. **Read both licences** (they're designed to be human-readable)
2. **Choose based on your values** and use case
3. **Include the appropriate LICENCE file** in your project
4. **If using both**, include both licence files

If you're unsure which licence to use, the MIT Licence is the safe, traditional choice. The Palimpsest Licence is for those who want stronger guarantees about attribution in AI systems.

=== Licence Compatibility

- **MIT is compatible** with Apache 2.0, BSD, GPL, and most other licences
- **Palimpsest is compatible** with MIT and other permissive licences
- **Both can coexist** in the same project (dual licensing)

=== Questions?

If you have questions about licensing:

- **MIT Licence**: See link:https://opensource.org/licenses/MIT[OSI's MIT Licence page]
- **Palimpsest Licence**: See link:https://github.com/hyperpolymath/palimpsest-license[Palimpsest Licence repository]
- **This project**: Open an issue in our link:{repo-url}/-/issues[issue tracker]

== 🙏 Acknowledgements

*REMINDER: Credit relevant communities/tools for each project, e.g.:*

- {Community, e.g. "Ada Community"}
- {Tool/Framework, e.g. "GNAT Ada Compiler"}
- {Ecosystem, e.g. "Rust, Elixir, or ReScript ecosystems"}
- Jonathan D.A. Jewell and contributors

== 🗺️ Roadmap

*REMINDER: Add if project has a detailed roadmap for dependencies and component handoffs.*

=== Current Phase
- {Current development focus}

=== Upcoming Features
- {Planned feature 1}
- {Planned feature 2}

=== Long-term Vision
- {Strategic direction}

See link:ROADMAP.adoc[ROADMAP.adoc] for detailed planning.

== 🌍 Impact & Ethical Alignment

*REMINDER: Include for projects tied to Governance Reform, Safeguarding, or other ethical concerns.*

This project aligns with:

- {Ethical framework, e.g. "Governance reform and transparency"}
- {Social impact, e.g. "Digital safeguarding"}
- {Professional alignment, e.g. "IETF contributions and union stewardship"}

== 📚 Additional Resources

- **Documentation**: link:docs/[Full documentation]
- **API Reference**: link:reference/[API reference]
- **Examples**: link:examples/[Example projects]
- **Community**: link:{repo-url}/-/discussions[Discussions]
- **Issue Tracker**: link:{repo-url}/-/issues[Report bugs or request features]

---

*This document uses UK-British Oxford English.*

*Template version: 1.0.0 | Last updated: {date}*
