Unknown `.apc/` Paths Should Not Become Hidden Instructions

Certain files within a repository's .apc/ folder should not be treated as hidden instructions. The Portable Context Layer specification advises consumers to disregard unknown paths unless a formal extension explicitly defines them. This guideline allows teams to explore without every local file becoming an instruction for all agents.

AGENTS.md and designated .apc/ paths carry project-specific context that persists across compatible tools. APX, the runtime layer, reads the project contract and maintains execution state like sessions and messages. The crucial distinction arises when a new file resembling authoritative data is added. For instance, a team might create .apc/triage-priority.md containing a list of customer incidents and a note to prioritize a queue.

A local script could read this file, while another tool scans the entire .apc/ directory, feeding each Markdown file to its agent as instructions. This results in varying behavior depending on which tool accesses the repository. The unknown-path rule prevents the second tool from unintentionally turning an experimental note into project policy.

Proper file location is essential to assign semantics. A consumer must recognize which APC path it is reading and its meaning. If it cannot identify the path, it should ignore it. Human reviewers should still be able to read the file; the key is that a generic APC reader should not create an interpretation. Define instructions on a clear surface if they need to be applied universally or to specific paths/tasks.

For example, put them in AGENTS.md or .apc/rules/ with a clear description and scope. If the instruction is for an agent invocation, use .apc/skills/. This ensures readers understand the content's reach and reviewers can determine if its scope is appropriate. Keep experimental data separate until its role is determined. A standard project document can provide background without claiming APC semantics.

If a new machine-readable APC capability is needed, define an extension instead of relying on a private filename convention. This allows consumers to deliberately support it and handle unsupported versions predictably. Unknown files should not contain credentials, raw conversations, caches, or private runtime memory. APC's documented layout keeps sensitive data in local runtime storage, with APX using ~/.apx/projects/ project-id / for project runtime state.

Ignoring an unknown path is a parsing rule, not a privacy control or justification for committing sensitive files. When reviewing a new .apc/ file, ask: Is this path defined by APC or an explicit extension? Does its content align with that path's purpose? Should it become an AGENTS.md rule, an APC rule or skill, or regular project documentation?

Would a compatible reader know when to load it without guessing? These questions help maintain the portable layer's predictability. APX can execute the project contract in daily work, while other compatible tools can read the same contract without inheriting unintended behaviors from files that might be present.