Add Architecture and Agent Documentation

.gitignore

@@ -23,3 +23,9 @@ stamp-h1
 testdrvr
 testsrvr
 *~
+m4/*.m4
+compile
+*.pc
+stdlog/stdlogctl
+stdlog/tester
+INSTALL

AGENTS.md

@@ -0,0 +1,61 @@
+# Instructions for AI Agents
+
+This file provides context and instructions for AI agents working on the `liblogging` repository.
+
+## Project Overview
+`liblogging` is a C library for logging, offering an enhanced replacement for `syslog(3)`.
+
+*   **Primary Component**: `stdlog` (Standard Logging) - Focus your efforts here.
+*   **Legacy Component**: `rfc3195` - Only touch if explicitly requested.
+
+## Build Instructions
+
+The project uses GNU Autotools.
+
+### Prerequisites
+*   gcc
+*   make
+*   autoconf, automake, libtool
+*   pkg-config
+*   rst2man (optional, for man pages)
+
+### Building form Source
+1.  **Generate build scripts**:
+    ```bash
+    autoreconf -fi
+    ```
+2.  **Configure**:
+    ```bash
+    ./configure
+    # If rst2man is missing:
+    ./configure --disable-man-pages
+    ```
+3.  **Compile**:
+    ```bash
+    make
+    ```
+
+## Directory Structure
+
+*   `stdlog/`: Source code for the main library.
+    *   `stdlog.c/h`: Main API implementation.
+    *   `*drvr.c`: Driver implementations (e.g., `file.c`, `uxsock.c`).
+    *   `tester.c`: Basic test utility.
+*   `rfc3195/`: Legacy RFC 3195 implementation.
+*   `m4/`: Autotools macros.
+
+## Testing
+
+*   **stdlog**: A basic tester binary is built in `stdlog/tester`.
+    *   Usage: `stdlog/tester -p "driver:specification"`
+    *   Example: `stdlog/tester -p "file:/tmp/test.log"`
+
+## Code Guidelines
+
+*   **Language**: C (C99/C11 compatible).
+*   **Style**: Follow the existing coding style (K&R-ish).
+*   **Safety**: Pay special attention to signal safety and thread safety in `stdlog`. Avoid using non-signal-safe functions (like `malloc`, `printf`) in critical paths if `STDLOG_SIGSAFE` is enabled.
+*   **Documentation**: Update `.rst` files in `stdlog/` when changing the API.
+
+## Known Issues
+*   The `journalemu` component mentioned in older documentation does not exist in the codebase.

ARCHITECTURE.md

@@ -0,0 +1,50 @@
+# Liblogging Architecture
+
+## Overview
+
+Liblogging is a lightweight, easy-to-use logging library for C applications. It aims to provide an enhanced replacement for the traditional `syslog(3)` API while maintaining simplicity and adding modern features like signal safety and multiple log destinations.
+
+## Components
+
+The repository is divided into two main components:
+
+### 1. stdlog (Standard Logging)
+This is the core, active component of the library. It is located in the `stdlog/` directory.
+
+*   **Purpose**: To provide a modern logging API that separates the logging call from the log destination.
+*   **Key Features**:
+    *   **Signal-Safe**: Can be safely called from within signal handlers (when initialized with `STDLOG_SIGSAFE`).
+    *   **Thread-Safe**: Supports multi-threaded applications.
+    *   **Driver-Based**: Uses a driver layer to send logs to different destinations.
+
+### 2. rfc3195 (Legacy)
+Located in the `rfc3195/` directory. This is an implementation of the RFC 3195 standard (syslog over BEEP). It is considered a legacy component and is not recommended for new applications.
+
+## stdlog Architecture
+
+The `stdlog` component is designed around a **Separation of Concerns** principle:
+*   **Application Developer**: Uses the `stdlog` API to emit log messages without worrying about where they go.
+*   **System Administrator**: Configures the logging driver (via environment variables or application configuration) to direct logs to the appropriate destination.
+
+### Drivers
+
+`stdlog` uses a driver model to handle the actual transmission or storage of log messages. Supported drivers include:
+
+*   **syslog**: Sends messages to the traditional system syslog daemon (e.g., via `/dev/log`).
+*   **journal**: Writes directly to the systemd journal using its native API.
+*   **file**: Writes messages to a specified file on the filesystem.
+*   **uxsock**: Sends messages to a specified Unix domain socket.
+
+### Data Flow
+
+1.  **Initialization**: The application initializes the library (optional, but recommended for threading/signal safety).
+2.  **Channel Creation**: A logging channel is opened via `stdlog_open()`. This selects the driver based on the provided connection string (or default).
+3.  **Logging**: The application calls `stdlog_log()` or related functions.
+4.  **Formatting**: The message is formatted (often into a syslog-like format) within the library.
+5.  **Dispatch**: The active driver takes the formatted message and transmits it to the destination (file, socket, journal, etc.).
+
+## Build System
+
+The project uses GNU Autotools (`autoconf`, `automake`, `libtool`).
+*   **configure.ac**: Main build configuration.
+*   **Makefile.am**: Automake definitions.

README.md

@@ -3,7 +3,7 @@ What?
 Liblogging is an easy to use library for logging. It offers an enhanced
 replacement for the syslog() call, but retains its ease of use.
 
-If you dig deeper, liblogging actually has three components, which address
+If you dig deeper, liblogging actually has two components, which address
 different needs.
 
 stdlog
@@ -42,14 +42,6 @@ An interesting side-effect of that approach is that an application developer
 can write code that natively logs to the journal on platforms that support
 it but uses different methods on platforms that do not.
 
-journalemu
-----------
-This component (not yet committed) emulates the most important logging
-calls of systemd journal. This permits applications to be written to this
-spec, even though the journal is not available on all platforms. Of course,
-we recommend writing directly to libstdlog, as this solves the problem
-more cleanly.
-
 rfc3195
 -------
 This is liblogging's original component. Back in 2002, we thought that