# CLAUDE.md — Tree::MultiNode

## What is this

A Perl module for modeling hierarchical data as multi-node trees. Each node has a key, a value, and an ordered list of children. Operations use a Handle (cursor) that points into the tree.

Three packages in one file (`lib/Tree/MultiNode.pm`):
- `Tree::MultiNode` — tree container (holds the top node)
- `Tree::MultiNode::Node` — individual node (key, value, children, parent)
- `Tree::MultiNode::Handle` — cursor for navigating and manipulating the tree

## Commands

```bash
perl Makefile.PL && make        # Build
make test                       # Run tests (t/)
prove -b xt/*.t                 # Extended tests (pod coverage)
prove -bv t/01-multinode.t      # Run a single test file verbosely
```

## Architecture

- Single-file module: `lib/Tree/MultiNode.pm`
- Tests: `t/00-load.t` (smoke), `t/01-multinode.t` (functional), `t/02-comprehensive.t` (full coverage), `t/03-bugfixes.t` (regression tests)
- Extended tests: `xt/` (pod, pod-coverage)
- CI: GitHub Actions across Linux (Perl 5.8–latest), macOS, Windows

## Conventions

- Tests use `Test::More` with a declared plan (`tests => N`)
- Tests run under taint mode (`#!perl -T`)
- No external dependencies beyond core Perl and Test::More
- `$Tree::MultiNode::debug` enables verbose debug prints throughout

## Known Issues

- Several methods used `shift || $self->{'curr_pos'}` which treats position 0 as falsy — fixed in PRs #2 and #3
- `Node::new()` had `$key || undef` which dropped falsy keys like `0` or `""` — fixed in PR #3
- POD for `remove_child` heading actually documented `kv_pairs` — fixed in PR #3
