Privacy Tiers

processkit recognizes three privacy tiers for entities under context/. The tier is declared via an optional privacy: field in metadata and enforced by directory layout + a .gitignore rule.

The three tiers

Most entities omit the field entirely and inherit project-private.

Filesystem rule for user-private

Entities with privacy: user-private MUST live under a directory named private/ somewhere within context/. Projects should carry a .gitignore rule like:

context/**/private/

This pattern matches private/ directories at any depth under context/, including directly under context/ itself. So all of these are excluded from git:

• context/private/
• context/owner/private/
• context/foo/bar/private/

But NOT directories named private/ outside context/ (e.g. cli/src/private/ would NOT be ignored by this rule).

Installers and validation tools should verify that any entity with privacy: user-private lives under a private/ directory under context/. A user-private entity outside such a directory is invalid.

Where the convention is used

• owner-profiling skill: context/owner/private/team-and-relationships.md is the canonical example. Notes about coworkers’ communication styles, sensitivities, and interpersonal dynamics should never be checked into a shared repository.
• Personal scratch notes: any project can have a context/private/ for personal drafts, half-formed ideas, or session notes that the agent should see but the team should not.
• API keys / secrets are NOT what this is for — those should be in environment variables or a secret manager. Privacy tiers are for human-readable content that’s sensitive but not credentialed.

Frontmatter example

---
apiVersion: processkit.projectious.work/v1
kind: Context
metadata:
  id: OWNER-team-and-relationships
  privacy: user-private
  created: 2026-04-07T00:00:00Z
spec:
  description: "Per-person notes about collaborators."
---

# Team and Relationships

> ⚠️ PRIVACY: user-private. This file lives under context/owner/private/
> which is gitignored.

...

Why directory enforcement, not just frontmatter

A frontmatter declaration alone wouldn’t prevent the file from being checked into git — git add doesn’t read frontmatter. The directory rule gives a hard guarantee via .gitignore. The frontmatter declaration is documentation + lint validation; the directory placement is the actual safety mechanism.

If you want a user-private file outside any private/ directory, you have two options:

1. Move it under a private/ directory (correct)
2. Override the validation rule in local tooling (discouraged because it defeats the safety mechanism)

Public files

privacy: public is documentation, not security — anything in a public git repo is already world-readable. The distinction between public and project-private only matters when the project is in a private repo: in that case public files are fine to syndicate to a public mirror or include in a generated README, while project-private files are not. For projects in public repos, public and project-private are functionally identical.

Docs-site filtering

Projects that build a documentation site from their context content must exclude private subtrees from the build. For the Hugo site processkit itself ships, that is a hugo.yaml entry:

ignoreFiles:
  - "/private/"

Other generators need the same rule expressed their own way — a Docusaurus docs preset, for example, takes exclude: ['**/private/**'].

This is the rule processkit’s own documentation build carries. It matches private/ directories at any depth, so context/private/, context/owner/private/, and any deeper nesting are all excluded.

Multi-user projects

For projects where multiple people work from the same repository, the current convention is flat context/private/: a single gitignored directory that is personal to whoever is running the agent locally.

A per-user subdirectory convention (context/private/<username>/) is not yet standardized. The actor primitive (actor-profile) captures identity but the privacy directory layout does not yet key on it. Defer the multi-user convention until a real project asks for it — at that point, context/private/<username>/ is the natural extension and requires no schema changes, only a new gitignore pattern.

This decision was recorded in response to aibox DEC-030 / processkit#1 .