# P4LF — AI Agent Notes

Read all session logs in `ai/` (sorted by date) to get up to speed on prior
work, decisions, and rationale before starting new work.

## Current Status

- v1.0.4 is released and promoted to `//p4lf/main`, with platform binaries
  built and submitted there.
- The customer's sandbox systemd install issue (p4lf.service failing to
  start via `EnvironmentFile=` sourcing of SDP's `p4_vars`) is fixed and
  **confirmed resolved by the customer** — see
  `ai/session_log_2026-08-25.md`.
- **P4LF-4** (fixed, CL 33291 dev / 33292 main): a fresh `install.sh` install
  left `p4lf.cfg`/`p4lf.cfg.example` root-owned, so the perforce-run systemd
  service couldn't read its own config (auto-restart/exit-code 1).
  `install.sh` now chowns those files to `perforce:perforce` at install time
  (with a warning fallback if that OS user doesn't exist), and re-asserts
  ownership on existing configs during upgrades. Script-only fix; no binary
  rebuild needed. Not yet confirmed by the customer.
- Open job: **P4LF-2** — perforce OS user service management (deferred, not
  blocking; currently requires root to start/stop the systemd service).
- `make check` passes on macOS; Linux/macOS amd64+arm64 binaries all build
  cleanly via `make build-all`.

## Background Info

There are two environments:
* **Local**: Copilot runs here on the developer's Mac, for development.
* **Sandbox**: The software is deployed and operating on a customer sandbox
  for testing. Copilot is not installed there and cannot be installed there.

On the customer's sandbox:
* A P4 workspace mapped to the `//p4lf/dev` stream deploys files to
  `/p4/common/site/p4lf_dev`.
* An "as deployed" directory `/p4/common/site/log_feeder` contains:
  * A local `p4lf.cfg` file with the customer's configuration.
  * A symlink `p4lf` pointing to
    `/p4/common/site/p4lf_dev/bin/p4lf-linux-amd64`.

So changes made and submitted in version control can easily be deployed to
the customer's runtime environment by re-syncing the `dev` workspace on the
sandbox. (Production deployment uses a different flow — `install.sh` against
the `main` or a release stream, not the raw `dev` stream.)

The sandbox has automation generating general P4LOG traffic (e.g. creating
`p4 jobs` in a loop) so there is frequent log activity, simulating a
production P4 server with active users.

## Quick Start on Linux

```bash
# Sync workspace (set up a //p4lf/dev client on the Linux machine first)
p4 sync

# Build (requires Go 1.20+; install via https://go.dev/dl/ if needed)
make build
bin/p4lf -version   # expect: p4lf <SemVer> (CL ..., //p4lf/dev#N, ...)

# Configure
cp p4lf.cfg.example /p4/common/site/log_feeder/p4lf.cfg
vi /p4/common/site/log_feeder/p4lf.cfg   # set P4LogFile at minimum

# Run in foreground for initial testing
bin/p4lf -config /p4/common/site/log_feeder/p4lf.cfg
```

## Key Files for Context

- `ai/P4WorkflowNotes.md` — P4 workflow, stream structure, how to create jobs.
- `docs/DeveloperGuide.md` — build/test/release tooling, versioning, and the
  dev → main → release-stream promotion workflow.
- `ai/session_log_*.md` — dated session logs; read newest-first for the most
  recent context, but older logs may hold useful historical rationale too.

# Version Control Interaction

Consult `ai/P4WorkflowNotes.md` for P4 workflow and version control details.

# The 'ai/' folder

The `ai/` directory under the workspace root is where this AGENTS.md file
lives; it is symlinked from the root of the workspace as
`copilot-instructions.md`.

The `ai/` folder stores this AGENTS.md file (updated as project state
evolves) and AI session logs — these are dev-support files, not part of the
shipped software. However, `ai/` folder contents are versioned in `//p4lf/dev`.

`ai/` (along with `bin/`) is configured as an **isolated** path in the
`//p4lf/main` stream spec, so it is not carried along when promoting `dev` to
`main` — see `docs/DeveloperGuide.md` for details.

For each session, write (or append to) a session log that captures
highlights of what was done, including prompts. Paraphrasing prompts is OK;
not all prompts need to be captured, only those useful in helping understand
the result of the session. Capture any important decisions that were made
(and why). The primary audience for session logs is a future agent
continuing the work, though they may also have training and audit value.