BUGS
 ==== ==== ==== ==== ==== ==== ==== ============ 
Users/rbutare/websites/system';
  const APP_NAME = 'defapp'; are set in defapp.index.php - need to be set to  in
  app to find key system files - we will have to test defapp.index.php without
  it being defined and see if it works - I think SYSTEM_ROOT may have replaced
  it add this to our task list to investigate; APP_NAME - in system/.env may be
  left over since app needs to set in app on initial load; 
 ==== ==== ==== ==== ==== ==== ==== ============ 
 TODO
 - find golden and new ai docs just defined
 ==== ==== ==== ==== ==== ==== ==== ============ 

- Hard-wrap prose at no more than 80 characters per line.
- Wrap checklist items with indented continuation lines.
- Use headings and lists instead of wide Markdown tables.
- Keep code within 80 columns where it can be safely formatted.
- Preserve long URLs, paths, and literals when wrapping would change them.
- Apply this to project plans, READMEs, FAQs, and other generated `.md` files.

## What you have supplied

I now have your directory listing, scanner output, and the pasted
`defapp.index.php` example. I still do not have the actual contents of
`src/fileflow.py`, the run scripts, or the supporting application files.

Your output gives us specific baseline cases to investigate:

- `__DIR__` references are being reported as unresolved.
- The tree command supplies a different `SYSTEM_ROOT` from the value in
  `defapp.index.php`.
- `$bootstrapFile` uses a computed path.
- `$pageSetup` contains paths that templates may load later.
- The run script attempts a missing `registry/registry.index.php`.
- The scanner output includes references corresponding to commented-out lines in
  the pasted source.

We should preserve these as test cases before changing the scanner.

## Replacement Markdown plan

The following version avoids wide tables and wraps its source lines within 80
columns. It can replace your current `projplan.md`.

```markdown # TraceFlow Project Plan

## Goal

Starting from an application entry file, discover its PHP, CSS, and JavaScript
dependencies and display their relationships.

Keep static source-reference order separate from observed runtime order.

## Documentation Rules

- Limit Markdown source lines to 80 characters.
- Hard-wrap paragraphs and checklist items.
- Use lists instead of wide tables.
- Preserve code, paths, URLs, and literals when wrapping would alter them.
- State what was tested and what remains unverified.

## Three Approaches

### 1. Static File-Flow Scanner

Discover file references without executing the target application.

Output:

- Recursive dependency tree.
- Referring file and source line.
- Relationship type and original path expression.
- Resolved, missing, external, or unresolved status.
- Source-reference order, not claimed runtime order.

### 2. PHP Runtime Tracing

Observe a particular PHP request or CLI execution.

Output:

- Observed PHP events and file inventory.
- Event sequence and timing where captured.
- Parent-child relationships where the capture supports them.
- Differences between static dependencies and observed activity.

### 3. Browser Runtime Tracing

Observe browser resources and instrumented JavaScript activity.

Output:

- Script and stylesheet resource activity.
- Instrumented JavaScript events.
- Instrumented fetch or AJAX activity.
- Correlation with server requests.
- Separate loading and execution information.

## Phase 0: Recover and Establish a Baseline

- [x] Receive the current TraceFlow directory listing.
- [x] Receive sample scanner output.
- [x] Receive the pasted defapp entry file.
- [x] Receive confirmation of the traceflow1 backup copy.
- [ ] Receive the current TraceFlow source package.
- [ ] Receive the entry template and relevant supporting files.
- [ ] Receive shared bootstrap.php and paths.php.
- [ ] Receive sanitized system and application path settings.
- [ ] Identify filesystem roots and browser URL mappings.
- [ ] Run existing tests before changing code.
- [ ] Record failures and preserve baseline reports.

Deliverable: an inventory of working, broken, and missing features.

## Phase 1: Reproduce the Current Failures

- [ ] Investigate unresolved __DIR__ references.
- [ ] Compare supplied constants with constants in the entry file.
- [ ] Test computed paths assigned to $bootstrapFile.
- [ ] Test paths assigned through $includesDir.
- [ ] Distinguish configured page paths from actual include operations.
- [ ] Investigate references found in commented-out code.
- [ ] Handle missing application entry files with clear diagnostics.
- [ ] Preserve source locations and original expressions in reports.

Deliverable: regression fixtures based on the supplied examples.

## Phase 2: Define Shared Resolution Rules

- [ ] Define configuration and command-line override precedence.
- [ ] Define system and application .env merge rules.
- [ ] Define allowed scan roots and exclusions.
- [ ] Define URL-to-filesystem mappings for local browser assets.
- [ ] Define missing, external, dynamic, repeated, and cyclic references.
- [ ] Define a shared JSON record format.
- [ ] Keep static scanning separate from application execution.

Deliverable: documented rules and expected fixture results.

## Phase 3: Build the Static Scanner

### PHP References

- [ ] Find include, include_once, require, and require_once.
- [ ] Ignore comments and unrelated string contents.
- [ ] Resolve literal paths and __DIR__.
- [ ] Resolve supported dirname() and concatenation expressions.
- [ ] Support DIRECTORY_SEPARATOR in path expressions.
- [ ] Resolve supported constant declarations.
- [ ] Resolve supported variable assignments.
- [ ] Report unsupported expressions without silently dropping them.
- [ ] Label conditional references where identified.

### Templates and Browser Assets

- [ ] Find script src and stylesheet link references.
- [ ] Follow supported JavaScript imports and re-exports.
- [ ] Follow literal dynamic imports as potential dependencies.
- [ ] Follow CSS @import references.
- [ ] Separate optional CSS url() assets from code dependencies.
- [ ] Resolve local asset URLs using explicit mappings.
- [ ] Mark external resources without attempting local resolution.

### Recursive Reports

- [ ] Traverse resolved dependencies recursively.
- [ ] Include allowed shared-system directories.
- [ ] Preserve source-reference order within each file.
- [ ] Show referring line numbers and relationship types.
- [ ] Detect cycles and repeated dependencies.
- [ ] Produce tree, flat text, and JSON output.
- [ ] Support relative, root-prefixed, and absolute path display.

Deliverable: a dependency tree for the fixture and defapp application.

## Phase 4: Add PHP Runtime Capture

- [ ] Review the existing PHP tracer.
- [ ] Select a mechanism for detailed include and execution events.
- [ ] Separate included-file inventory from detailed tracing.
- [ ] Capture request IDs and event sequence numbers.
- [ ] Capture calling locations and timing where supported.
- [ ] Keep tracing disabled by default.
- [ ] Test conditional and repeated includes.
- [ ] Test include_once, autoloading, and failed includes.
- [ ] Compare runtime observations with the static report.
- [ ] Document capture limitations.

Deliverable: an observed server-side timeline.

## Phase 5: Add Browser Runtime Capture

- [ ] Review the existing JavaScript tracer.
- [ ] Correlate browser activity with server requests.
- [ ] Capture script and stylesheet resource activity.
- [ ] Capture explicit JavaScript execution markers.
- [ ] Capture instrumented fetch and AJAX events.
- [ ] Distinguish resource loading from execution.
- [ ] Test deferred, asynchronous, module, and dynamic scripts.
- [ ] Avoid logging credentials or private server configuration.
- [ ] Keep browser capture optional.

Deliverable: an observed client-side timeline.

## Phase 6: Integrate and Package

- [ ] Combine reports without hiding their evidence type.
- [ ] Mark statically found and runtime-observed dependencies.
- [ ] Mark dependencies not observed during the selected run.
- [ ] Preserve separate server and browser event sequences.
- [ ] Provide filters for PHP, JavaScript, CSS, and unresolved paths.
- [ ] Run fixture tests and available runtime checks.
- [ ] Verify macOS and target Linux path handling.
- [ ] Update documentation using the 80-column rule.
- [ ] Deliver one atomic package with a validation command.
- [ ] Include a completion report and known limitations.

## First Milestone

For defapp/defapp.index.php:

- Resolve supported PHP include paths.
- Follow the entry template and nested dependencies.
- Discover supported CSS and JavaScript references.
- Show source locations and a recursive dependency tree.
- Report every unresolved reference explicitly.
- Do not claim that the static tree is an execution timeline.

## Next Input Needed