From 296a1362f61c2965a3277608694b0ff4b06add53 Mon Sep 17 00:00:00 2001
From: Toddr Bot <toddbot@rinaldo.us>
Date: Mon, 6 Apr 2026 03:14:36 +0000
Subject: [PATCH] add CLAUDE.md with project guidelines for AI agents

Documents build/test workflow, generated files (MANIFEST, README.md),
and the rule that releases/versioning are human-only.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 CLAUDE.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 68 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..c09fc8e
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,68 @@
+# CLAUDE.md
+
+Guidelines for AI agents working on this repository.
+
+## Project overview
+
+Net::Daemon is a Perl CPAN module providing a base class for implementing TCP/IP daemons.
+It supports forking, ithreads, and single-connection server modes with built-in logging,
+config file handling, and access control.
+
+- **Primary module**: `lib/Net/Daemon.pm`
+- **Submodules**: `lib/Net/Daemon/Log.pm` (logging), `lib/Net/Daemon/Test.pm` (test support)
+- **License**: Perl 5 (Artistic or GPL)
+- **Minimum Perl**: 5.006
+
+## Build and test
+
+```bash
+perl Makefile.PL    # Generate Makefile (ExtUtils::MakeMaker)
+make                # Build
+make test           # Run test suite
+make disttest       # Build dist and test it
+make manifest       # Regenerate MANIFEST
+```
+
+## Generated files -- do not edit
+
+- **`MANIFEST`** -- Generated by `make manifest`. Do not manually edit or re-sort.
+- **`README.md`** -- Generated by running `pod2markdown` on the primary module file
+  (`lib/Net/Daemon.pm`). Do not edit directly; update the POD in the module instead.
+
+## Releases and versioning
+
+Releases are performed **manually by the human maintainer**. Fixes and PRs must never:
+
+- Bump the version number (`$VERSION` in `lib/Net/Daemon.pm`)
+- Update `ChangeLog`
+- Modify release-related metadata
+
+These are handled exclusively during the release process.
+
+## Code style
+
+- Perl code is formatted with `perltidy` (see `.perltidyrc` for settings)
+- 4-space indentation, 400-character line limit
+- Use `strict` and `warnings` in all Perl files
+
+## Test suite
+
+- Tests live in `t/` and use `Test::More`
+- The test harness uses `Net::Daemon::Test` for server/client test infrastructure
+- Several tests require fork or ithread support and will skip on unsupported platforms
+- CI runs on Linux (Perl 5.8+), macOS, and Windows via GitHub Actions
+
+## Repository structure
+
+```
+lib/Net/Daemon.pm          # Main module
+lib/Net/Daemon/Log.pm      # Logging support
+lib/Net/Daemon/Test.pm     # Test infrastructure
+t/                         # Test suite
+t/server                   # Test server script
+Makefile.PL                # Build configuration
+cpanfile                   # Dependency declarations
+ChangeLog                  # Release history (human-maintained)
+AI_POLICY.md               # AI usage policy for this project
+.github/workflows/         # CI configuration
+```