folder-nature 0.1.0__py3-none-any.whl

folder_nature/__init__.py

@@ -0,0 +1,57 @@
+"""folder-nature — semantic identity for filesystem folders.
+
+A directory becomes a conversation partner: it has identity, purpose, rules,
+and history, all captured in a hidden ``.folder-nature`` YAML file.
+
+Public API:
+
+    from folder_nature import (
+        FolderNature,
+        SchemaError,
+        find_director,
+        get_folder_nature,
+        write_folder_nature,
+        search,
+        validate,
+    )
+
+CLI entry point: ``folder-nature`` (see ``folder_nature.cli``).
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+__schema_version__ = "1.0"
+
+from .schema import (
+    FolderNature,
+    SchemaError,
+    SCHEMA_VERSION,
+    BEING_TYPES,
+    validate as validate_data,
+)
+from .core import (
+    find_director,
+    get_folder_nature,
+    read_folder_nature,
+    write_folder_nature,
+    NATURE_FILENAME,
+)
+from .search import search, list_all
+
+__all__ = [
+    "__version__",
+    "__schema_version__",
+    "FolderNature",
+    "SchemaError",
+    "SCHEMA_VERSION",
+    "BEING_TYPES",
+    "NATURE_FILENAME",
+    "validate_data",
+    "find_director",
+    "get_folder_nature",
+    "read_folder_nature",
+    "write_folder_nature",
+    "search",
+    "list_all",
+]

folder_nature/cli.py

@@ -0,0 +1,314 @@
+"""Command-line interface — the ``folder-nature`` binary.
+
+Subcommands (MVP):
+    init        Create a new .folder-nature in the target directory
+    show        Print the closest .folder-nature (walks up from target)
+    query       Find the director ancestor of target
+    search      Find folders matching --tag/--being/--name
+    validate    Check schema-validity of all .folder-nature files in tree
+    list        Tree-view of every .folder-nature
+    version     Print tool + schema versions
+
+Phase 2 (post-MVP) subcommands: ai-suggest, watch, migrate, export, import.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib.resources as pkg_resources
+import sys
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+from . import __schema_version__, __version__
+from .core import (
+    NATURE_FILENAME,
+    find_director,
+    get_folder_nature,
+    read_folder_nature,
+    write_folder_nature,
+)
+from .schema import (
+    BEING_TYPES,
+    FolderNature,
+    Identity,
+    Memory,
+    SchemaError,
+    from_dict,
+)
+from .search import iter_nature_file_paths, list_all, search
+
+
+# Default templates ship in the package; user-selectable via ``--template``.
+DEFAULT_TEMPLATES = (
+    "workspace",
+    "client-project",
+    "archive",
+    "deployment",
+    "documentation",
+)
+
+
+# ── Template loading ────────────────────────────────────────────────────────
+
+
+def _load_template(name: str) -> dict:
+    """Load a template from the packaged templates dir.
+
+    Returns the parsed YAML dict. Raises :class:`FileNotFoundError` if name
+    isn't a known template.
+    """
+    try:
+        # importlib.resources for Python 3.9+; falls back to traversable
+        files = pkg_resources.files("folder_nature.templates")
+        candidate = files / f"{name}.yaml"
+        if not candidate.is_file():
+            raise FileNotFoundError(
+                f"unknown template {name!r}. "
+                f"Available: {', '.join(sorted(DEFAULT_TEMPLATES))}"
+            )
+        return yaml.safe_load(candidate.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        raise
+
+
+# ── Subcommand handlers ────────────────────────────────────────────────────
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    """folder-nature init [PATH] [--template NAME]"""
+    target = Path(args.path).resolve()
+    if not target.exists():
+        print(f"folder-nature: error: directory does not exist: {target}", file=sys.stderr)
+        return 2
+    if not target.is_dir():
+        print(f"folder-nature: error: not a directory: {target}", file=sys.stderr)
+        return 2
+
+    nature_file = target / NATURE_FILENAME
+    if nature_file.exists() and not args.force:
+        print(
+            f"folder-nature: error: {NATURE_FILENAME} already exists at {target}. "
+            "Use --force to overwrite.",
+            file=sys.stderr,
+        )
+        return 1
+
+    if args.template:
+        try:
+            data = _load_template(args.template)
+        except FileNotFoundError as e:
+            print(f"folder-nature: error: {e}", file=sys.stderr)
+            return 2
+        # If --name is provided, override the template's identity.name with
+        # the actual directory name (templates use placeholder).
+        if "identity" in data and isinstance(data["identity"], dict):
+            data["identity"].setdefault("name", target.name)
+            if args.name:
+                data["identity"]["name"] = args.name
+        try:
+            nature = from_dict(data)
+        except SchemaError as e:
+            print(f"folder-nature: error: template {args.template!r} invalid: {e}",
+                  file=sys.stderr)
+            return 1
+    else:
+        # Minimal nature without template — user provides name/being/purpose
+        if not (args.name and args.being and args.purpose):
+            print(
+                "folder-nature: error: without --template, you must provide "
+                "--name, --being, and --purpose",
+                file=sys.stderr,
+            )
+            print(
+                f"  Or pick a template with --template (one of: "
+                f"{', '.join(sorted(DEFAULT_TEMPLATES))})",
+                file=sys.stderr,
+            )
+            return 2
+        nature = FolderNature(
+            identity=Identity(
+                name=args.name,
+                being=args.being,
+                purpose=args.purpose,
+            ),
+            director=args.director,
+            tags=args.tag or [],
+        )
+
+    try:
+        written_path = write_folder_nature(target, nature)
+    except SchemaError as e:
+        print(f"folder-nature: error: validation failed: {e}", file=sys.stderr)
+        return 1
+    print(f"created {written_path}")
+    return 0
+
+
+def cmd_show(args: argparse.Namespace) -> int:
+    """folder-nature show [PATH] — print closest .folder-nature."""
+    target = Path(args.path).resolve()
+    nature = get_folder_nature(target)
+    if nature is None:
+        print(
+            f"folder-nature: no {NATURE_FILENAME} found in {target} or any ancestor",
+            file=sys.stderr,
+        )
+        return 1
+    print(yaml.safe_dump(
+        nature.to_dict(),
+        sort_keys=False,
+        allow_unicode=True,
+        default_flow_style=False,
+    ).rstrip())
+    return 0
+
+
+def cmd_query(args: argparse.Namespace) -> int:
+    """folder-nature query [PATH] — find director ancestor."""
+    target = Path(args.path).resolve()
+    director_path, nature = find_director(target)
+    if director_path is None or nature is None:
+        print(
+            f"folder-nature: no director found walking up from {target}",
+            file=sys.stderr,
+        )
+        return 1
+    print(f"{director_path}")
+    if args.verbose:
+        print()
+        print(yaml.safe_dump(
+            nature.to_dict(),
+            sort_keys=False,
+            allow_unicode=True,
+            default_flow_style=False,
+        ).rstrip())
+    return 0
+
+
+def cmd_search(args: argparse.Namespace) -> int:
+    """folder-nature search [--tag X] [--being Y] [--name Z] [ROOT]"""
+    root = Path(args.root).resolve()
+    results = search(root, tag=args.tag, being=args.being, name=args.name)
+    if not results:
+        print(f"folder-nature: no matches under {root}", file=sys.stderr)
+        return 1
+    for nature in results:
+        if nature.identity is None:
+            continue
+        tags = ",".join(nature.tags) if nature.tags else "-"
+        print(f"{nature.identity.being:14s}  {nature.identity.name:30s}  tags=[{tags}]")
+    return 0
+
+
+def cmd_validate(args: argparse.Namespace) -> int:
+    """folder-nature validate [ROOT] — schema-check all .folder-nature files."""
+    root = Path(args.root).resolve()
+    total = 0
+    errors = 0
+    for nf in iter_nature_file_paths(root):
+        total += 1
+        try:
+            read_folder_nature(nf)
+        except SchemaError as e:
+            errors += 1
+            print(f"INVALID  {nf}: {e}")
+        except yaml.YAMLError as e:
+            errors += 1
+            print(f"BAD-YAML {nf}: {e}")
+        except OSError as e:
+            errors += 1
+            print(f"IO-ERROR {nf}: {e}")
+    print(f"\nchecked {total} file(s), {errors} error(s)")
+    return 0 if errors == 0 else 1
+
+
+def cmd_list(args: argparse.Namespace) -> int:
+    """folder-nature list [ROOT] — tree-view of all .folder-nature files."""
+    root = Path(args.root).resolve()
+    natures = list_all(root)
+    if not natures:
+        print(f"folder-nature: no .folder-nature files under {root}", file=sys.stderr)
+        return 1
+    for nature in natures:
+        if nature.identity is None:
+            continue
+        tags = ",".join(nature.tags) if nature.tags else "-"
+        marker = "*" if nature.director else " "
+        print(
+            f"{marker} {nature.identity.being:14s}  {nature.identity.name:30s}  "
+            f"tags=[{tags}]"
+        )
+    print(f"\n{len(natures)} folder-nature file(s) under {root}")
+    return 0
+
+
+def cmd_version(args: argparse.Namespace) -> int:
+    """folder-nature version"""
+    print(f"folder-nature {__version__}  (schema v{__schema_version__})")
+    return 0
+
+
+# ── argparse plumbing ──────────────────────────────────────────────────────
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="folder-nature",
+        description="Semantic identity for filesystem folders.",
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_init = sub.add_parser("init", help="Create a new .folder-nature in directory")
+    p_init.add_argument("path", nargs="?", default=".", help="Target directory (default: cwd)")
+    p_init.add_argument("--template", choices=sorted(DEFAULT_TEMPLATES),
+                        help="Use a packaged template")
+    p_init.add_argument("--name", help="identity.name (overrides template default)")
+    p_init.add_argument("--being", choices=sorted(BEING_TYPES),
+                        help="identity.being (required without --template)")
+    p_init.add_argument("--purpose", help="identity.purpose (required without --template)")
+    p_init.add_argument("--tag", action="append", help="Add a tag (repeatable)")
+    p_init.add_argument("--director", action="store_true", help="Mark as director")
+    p_init.add_argument("--force", action="store_true", help="Overwrite existing")
+    p_init.set_defaults(func=cmd_init)
+
+    p_show = sub.add_parser("show", help="Print closest .folder-nature")
+    p_show.add_argument("path", nargs="?", default=".")
+    p_show.set_defaults(func=cmd_show)
+
+    p_query = sub.add_parser("query", help="Find director ancestor")
+    p_query.add_argument("path", nargs="?", default=".")
+    p_query.add_argument("--verbose", "-v", action="store_true",
+                         help="Also print the director's .folder-nature content")
+    p_query.set_defaults(func=cmd_query)
+
+    p_search = sub.add_parser("search", help="Find folders matching criteria")
+    p_search.add_argument("root", nargs="?", default=".")
+    p_search.add_argument("--tag", help="Substring match against tags")
+    p_search.add_argument("--being", choices=sorted(BEING_TYPES))
+    p_search.add_argument("--name", help="Substring match against name")
+    p_search.set_defaults(func=cmd_search)
+
+    p_validate = sub.add_parser("validate", help="Schema-check tree")
+    p_validate.add_argument("root", nargs="?", default=".")
+    p_validate.set_defaults(func=cmd_validate)
+
+    p_list = sub.add_parser("list", help="Tree-view of all .folder-nature files")
+    p_list.add_argument("root", nargs="?", default=".")
+    p_list.set_defaults(func=cmd_list)
+
+    sub.add_parser("version", help="Print version").set_defaults(func=cmd_version)
+
+    return parser
+
+
+def main(argv: Optional[list] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

folder_nature/core.py

@@ -0,0 +1,116 @@
+"""Filesystem operations on ``.folder-nature`` files.
+
+Read, write, walk-upward-to-director. All paths are :class:`pathlib.Path`.
+YAML I/O via PyYAML.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterator, Optional, Tuple
+
+import yaml
+
+from .schema import FolderNature, from_dict, SchemaError, SCHEMA_VERSION
+
+
+NATURE_FILENAME = ".folder-nature"
+
+
+def _walk_upward(start: Path) -> Iterator[Path]:
+    """Yield ancestor directories of ``start`` (inclusive), stopping at root.
+
+    Ensures the walk always terminates — yields each ancestor exactly once,
+    stops when ``current.parent == current`` (filesystem root).
+    """
+    current = start.resolve()
+    if current.is_file():
+        current = current.parent
+    seen = set()
+    while True:
+        if current in seen:
+            return
+        seen.add(current)
+        yield current
+        parent = current.parent
+        if parent == current:
+            return
+        current = parent
+
+
+def read_folder_nature(path: Path) -> FolderNature:
+    """Read + validate a single ``.folder-nature`` file at ``path``.
+
+    Raises :class:`FileNotFoundError` if path doesn't exist.
+    Raises :class:`SchemaError` if file content fails validation.
+    Raises :class:`yaml.YAMLError` if file isn't valid YAML.
+    """
+    path = Path(path)
+    if not path.exists():
+        raise FileNotFoundError(f"no such file: {path}")
+    with path.open("r", encoding="utf-8") as f:
+        data = yaml.safe_load(f)
+    if data is None:
+        raise SchemaError(f"{path}: file is empty or contains only YAML null")
+    return from_dict(data)
+
+
+def write_folder_nature(directory: Path, nature: FolderNature) -> Path:
+    """Write a FolderNature to ``directory/.folder-nature``.
+
+    Validates the nature before writing. Returns the path written.
+    Overwrites existing file (caller's responsibility to confirm).
+    """
+    directory = Path(directory)
+    if not directory.exists():
+        raise FileNotFoundError(f"directory does not exist: {directory}")
+    if not directory.is_dir():
+        raise NotADirectoryError(f"not a directory: {directory}")
+
+    nature.validate()
+    target = directory / NATURE_FILENAME
+    with target.open("w", encoding="utf-8") as f:
+        yaml.safe_dump(
+            nature.to_dict(),
+            f,
+            sort_keys=False,
+            allow_unicode=True,
+            default_flow_style=False,
+        )
+    return target
+
+
+def get_folder_nature(path: Path) -> Optional[FolderNature]:
+    """Return the closest ``.folder-nature`` walking upward from ``path``.
+
+    Returns ``None`` if no ``.folder-nature`` exists in any ancestor.
+    Raises :class:`SchemaError` if the closest file is invalid (caller can
+    catch + try the next ancestor if desired).
+    """
+    for ancestor in _walk_upward(Path(path)):
+        nature_file = ancestor / NATURE_FILENAME
+        if nature_file.exists():
+            return read_folder_nature(nature_file)
+    return None
+
+
+def find_director(path: Path) -> Tuple[Optional[Path], Optional[FolderNature]]:
+    """Walk upward until finding a folder-nature with ``director: true``.
+
+    Returns ``(director_path, nature)`` or ``(None, None)`` if no director
+    is found in any ancestor.
+
+    Skips ancestors with invalid folder-nature files (logs nothing — caller
+    can run ``validate`` to find broken files explicitly).
+    """
+    for ancestor in _walk_upward(Path(path)):
+        nature_file = ancestor / NATURE_FILENAME
+        if not nature_file.exists():
+            continue
+        try:
+            nature = read_folder_nature(nature_file)
+        except (SchemaError, yaml.YAMLError):
+            continue
+        if nature.director:
+            return ancestor, nature
+    return None, None

folder_nature/schema.py

@@ -0,0 +1,247 @@
+"""Schema v1.0 — defines the shape of a ``.folder-nature`` file.
+
+A folder-nature is structured YAML with required + optional fields and a
+controlled vocabulary for the ``identity.being`` field. Schema is versioned
+so future bumps can migrate cleanly via :mod:`folder_nature.migrate`.
+
+This module is pure — no filesystem I/O, no YAML parsing. Just dataclasses
+and validation. Use :mod:`folder_nature.core` for read/write.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, asdict
+from datetime import date
+from typing import Any, Dict, List, Optional
+
+
+SCHEMA_VERSION = "1.0"
+
+# Controlled vocabulary for `identity.being`. Extensible — unknown values
+# log a warning during validation but don't reject the file.
+BEING_TYPES = frozenset({
+    "director",       # root/boss folder, children inherit
+    "collector",      # archive/historical storage
+    "workspace",      # active working space
+    "assets",         # non-code resources (images, fonts, media)
+    "configs",        # system/app configuration
+    "documentation",  # docs, references, guides
+    "ideas",          # unstructured exploration
+    "external",       # third-party content (vendored, downloaded)
+    "legal",          # contracts, agreements, compliance
+    "team-shared",    # multi-person collaboration
+    "private",        # sensitive/restricted
+    "system",         # system-managed (don't manually edit)
+})
+
+# Field-level constraints
+MAX_NAME_LEN = 100
+MAX_PURPOSE_LEN = 500
+MAX_TAG_LEN = 30
+MAX_RULE_LEN = 500
+MAX_TAGS_COUNT = 50
+MAX_RULES_COUNT = 100
+
+
+class SchemaError(ValueError):
+    """Raised on validation failure. Message names the offending field."""
+
+
+@dataclass
+class Identity:
+    """The mandatory identity block of a folder-nature."""
+    name: str
+    being: str
+    purpose: str
+
+
+@dataclass
+class Memory:
+    """Optional historical context. All fields optional within the block."""
+    created: Optional[str] = None                      # ISO date YYYY-MM-DD
+    last_significant_change: Optional[str] = None       # ISO date
+    notable_events: List[str] = field(default_factory=list)
+
+
+@dataclass
+class FolderNature:
+    """A parsed, validated folder-nature record.
+
+    Construct via :func:`folder_nature.schema.from_dict` (does validation) or
+    by manual instantiation + explicit :meth:`validate` call.
+    """
+    schema_version: str = SCHEMA_VERSION
+    identity: Optional[Identity] = None
+    director: bool = False
+    tags: List[str] = field(default_factory=list)
+    rules: List[str] = field(default_factory=list)
+    memory: Optional[Memory] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to a YAML-friendly dict. Drops None values for cleanliness."""
+        out: Dict[str, Any] = {"schema_version": self.schema_version}
+        if self.identity is not None:
+            out["identity"] = {
+                "name": self.identity.name,
+                "being": self.identity.being,
+                "purpose": self.identity.purpose,
+            }
+        out["director"] = self.director
+        if self.tags:
+            out["tags"] = list(self.tags)
+        if self.rules:
+            out["rules"] = list(self.rules)
+        if self.memory is not None:
+            mem: Dict[str, Any] = {}
+            if self.memory.created:
+                mem["created"] = self.memory.created
+            if self.memory.last_significant_change:
+                mem["last_significant_change"] = self.memory.last_significant_change
+            if self.memory.notable_events:
+                mem["notable_events"] = list(self.memory.notable_events)
+            if mem:
+                out["memory"] = mem
+        return out
+
+    def validate(self) -> None:
+        """Run all schema checks. Raises SchemaError on first violation."""
+        validate(self.to_dict())
+
+
+def from_dict(data: Dict[str, Any]) -> FolderNature:
+    """Construct + validate a FolderNature from a parsed YAML dict.
+
+    Raises :class:`SchemaError` if the dict doesn't conform.
+    """
+    validate(data)
+
+    identity_raw = data["identity"]
+    identity = Identity(
+        name=identity_raw["name"],
+        being=identity_raw["being"],
+        purpose=identity_raw["purpose"],
+    )
+
+    memory: Optional[Memory] = None
+    if "memory" in data:
+        mem_raw = data["memory"]
+        memory = Memory(
+            created=mem_raw.get("created"),
+            last_significant_change=mem_raw.get("last_significant_change"),
+            notable_events=list(mem_raw.get("notable_events", [])),
+        )
+
+    return FolderNature(
+        schema_version=data.get("schema_version", SCHEMA_VERSION),
+        identity=identity,
+        director=bool(data.get("director", False)),
+        tags=list(data.get("tags", [])),
+        rules=list(data.get("rules", [])),
+        memory=memory,
+    )
+
+
+def validate(data: Dict[str, Any]) -> None:
+    """Validate a parsed YAML dict against schema v1.0.
+
+    Raises :class:`SchemaError` with a descriptive message on first violation.
+    Returns None on success.
+    """
+    if not isinstance(data, dict):
+        raise SchemaError("root must be a mapping/dict")
+
+    # schema_version
+    version = data.get("schema_version")
+    if version is None:
+        raise SchemaError("schema_version is required")
+    if not isinstance(version, str):
+        raise SchemaError(f"schema_version must be a string, got {type(version).__name__}")
+    if version != SCHEMA_VERSION:
+        raise SchemaError(
+            f"unsupported schema_version {version!r}; "
+            f"this build supports {SCHEMA_VERSION!r} only. "
+            "Use `folder-nature migrate` for older versions."
+        )
+
+    # identity (required)
+    if "identity" not in data:
+        raise SchemaError("identity block is required")
+    identity = data["identity"]
+    if not isinstance(identity, dict):
+        raise SchemaError("identity must be a mapping/dict")
+
+    for fname in ("name", "being", "purpose"):
+        if fname not in identity:
+            raise SchemaError(f"identity.{fname} is required")
+        val = identity[fname]
+        if not isinstance(val, str):
+            raise SchemaError(f"identity.{fname} must be a string")
+        if not val.strip():
+            raise SchemaError(f"identity.{fname} must be non-empty")
+
+    if len(identity["name"]) > MAX_NAME_LEN:
+        raise SchemaError(f"identity.name exceeds {MAX_NAME_LEN} chars")
+    if len(identity["purpose"]) > MAX_PURPOSE_LEN:
+        raise SchemaError(f"identity.purpose exceeds {MAX_PURPOSE_LEN} chars")
+
+    being = identity["being"]
+    if being not in BEING_TYPES:
+        # Unknown but not rejected — extensibility hatch. Soft warning only.
+        # (Validation passes; a callable warning hook could be added later.)
+        pass
+
+    # director (optional, bool)
+    if "director" in data and not isinstance(data["director"], bool):
+        raise SchemaError("director must be a boolean")
+
+    # tags (optional, list of short strings)
+    if "tags" in data:
+        tags = data["tags"]
+        if not isinstance(tags, list):
+            raise SchemaError("tags must be a list")
+        if len(tags) > MAX_TAGS_COUNT:
+            raise SchemaError(f"tags count exceeds {MAX_TAGS_COUNT}")
+        for i, tag in enumerate(tags):
+            if not isinstance(tag, str):
+                raise SchemaError(f"tags[{i}] must be a string")
+            if len(tag) > MAX_TAG_LEN:
+                raise SchemaError(f"tags[{i}] exceeds {MAX_TAG_LEN} chars")
+            if not tag.strip():
+                raise SchemaError(f"tags[{i}] must be non-empty")
+
+    # rules (optional, list of strings)
+    if "rules" in data:
+        rules = data["rules"]
+        if not isinstance(rules, list):
+            raise SchemaError("rules must be a list")
+        if len(rules) > MAX_RULES_COUNT:
+            raise SchemaError(f"rules count exceeds {MAX_RULES_COUNT}")
+        for i, rule in enumerate(rules):
+            if not isinstance(rule, str):
+                raise SchemaError(f"rules[{i}] must be a string")
+            if len(rule) > MAX_RULE_LEN:
+                raise SchemaError(f"rules[{i}] exceeds {MAX_RULE_LEN} chars")
+
+    # memory (optional, dict)
+    if "memory" in data:
+        mem = data["memory"]
+        if not isinstance(mem, dict):
+            raise SchemaError("memory must be a mapping/dict")
+        for date_field in ("created", "last_significant_change"):
+            if date_field in mem and mem[date_field] is not None:
+                if not isinstance(mem[date_field], str):
+                    raise SchemaError(f"memory.{date_field} must be a string (ISO date)")
+                # Light date format check — YYYY-MM-DD
+                val = mem[date_field]
+                if len(val) >= 10 and val[4] == "-" and val[7] == "-":
+                    try:
+                        date.fromisoformat(val[:10])
+                    except ValueError as e:
+                        raise SchemaError(f"memory.{date_field} not a valid ISO date: {e}")
+        if "notable_events" in mem:
+            events = mem["notable_events"]
+            if not isinstance(events, list):
+                raise SchemaError("memory.notable_events must be a list")
+            for i, ev in enumerate(events):
+                if not isinstance(ev, str):
+                    raise SchemaError(f"memory.notable_events[{i}] must be a string")

folder_nature/search.py

@@ -0,0 +1,131 @@
+"""Search + list operations over a directory tree.
+
+These functions walk the filesystem looking for ``.folder-nature`` files and
+filter/sort by tag, being, or schema-validity. Walking respects standard
+exclude patterns (hidden dirs starting with ``.`` other than the user's
+content roots, virtual environments, build artifacts).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterator, List, Optional
+
+import yaml
+
+from .core import NATURE_FILENAME, read_folder_nature
+from .schema import FolderNature, SchemaError
+
+
+# Directory names skipped during search/list — performance + sanity.
+# Hidden directories (starting with ``.``) are also skipped EXCEPT this list
+# (which lets the tool find folders that intentionally start with a dot).
+_SKIP_DIRS = frozenset({
+    "__pycache__",
+    "node_modules",
+    ".git",
+    ".venv",
+    "venv",
+    "env",
+    ".tox",
+    ".pytest_cache",
+    "build",
+    "dist",
+    ".eggs",
+    ".mypy_cache",
+    ".ruff_cache",
+})
+
+
+def _iter_nature_files(root: Path) -> Iterator[Path]:
+    """Yield every ``.folder-nature`` file under ``root``, depth-first.
+
+    Skips directories in :data:`_SKIP_DIRS` and hidden directories (starting
+    with ``.`` and length > 1) for performance + cleanliness. The root itself
+    is always searched even if it starts with a dot.
+    """
+    root = Path(root).resolve()
+    if not root.exists() or not root.is_dir():
+        return
+
+    stack: List[Path] = [root]
+    while stack:
+        current = stack.pop()
+        try:
+            children = list(current.iterdir())
+        except (OSError, PermissionError):
+            continue
+
+        # First, check this directory itself for a folder-nature file
+        nature_file = current / NATURE_FILENAME
+        if nature_file.exists() and nature_file.is_file():
+            yield nature_file
+
+        # Then descend into subdirectories
+        for child in children:
+            if not child.is_dir():
+                continue
+            name = child.name
+            if name in _SKIP_DIRS:
+                continue
+            # Skip hidden dirs unless this is the search root
+            if name.startswith(".") and len(name) > 1:
+                continue
+            stack.append(child)
+
+
+def list_all(root: Path) -> List[FolderNature]:
+    """Return every valid FolderNature found under ``root`` (depth-first).
+
+    Invalid YAML or schema violations are silently skipped — use
+    :func:`folder_nature.cli.validate_tree` to report errors explicitly.
+    """
+    out: List[FolderNature] = []
+    for nf in _iter_nature_files(root):
+        try:
+            out.append(read_folder_nature(nf))
+        except (SchemaError, yaml.YAMLError, OSError):
+            continue
+    return out
+
+
+def search(
+    root: Path,
+    *,
+    tag: Optional[str] = None,
+    being: Optional[str] = None,
+    name: Optional[str] = None,
+) -> List[FolderNature]:
+    """Filter folder-natures under ``root`` by tag / being / name.
+
+    All filters are AND-combined. ``None`` for a filter means "don't filter".
+    Tag/name matching is substring + case-insensitive; ``being`` is exact match.
+
+    Returns the matching natures in walk order (depth-first).
+    """
+    out: List[FolderNature] = []
+    tag_lower = tag.lower() if tag else None
+    name_lower = name.lower() if name else None
+
+    for nature in list_all(root):
+        if being is not None and nature.identity is not None:
+            if nature.identity.being != being:
+                continue
+        if tag_lower is not None:
+            if not any(tag_lower in t.lower() for t in nature.tags):
+                continue
+        if name_lower is not None and nature.identity is not None:
+            if name_lower not in nature.identity.name.lower():
+                continue
+        out.append(nature)
+
+    return out
+
+
+def iter_nature_file_paths(root: Path) -> Iterator[Path]:
+    """Public iterator over .folder-nature file paths (no validation).
+
+    Useful for the ``list`` and ``validate`` CLI commands which need paths
+    even for invalid files.
+    """
+    yield from _iter_nature_files(root)

folder_nature/templates/archive.yaml

@@ -0,0 +1,13 @@
+schema_version: "1.0"
+identity:
+  name: archive                         # TODO: customize via --name
+  being: collector
+  purpose: Historical / inactive artifacts retained for reference
+director: false
+tags:
+  - archive
+  - inactive
+  - reference
+rules:
+  - Do not modify archived content; create a new working copy if changes needed
+  - Review for retention annually

folder_nature/templates/client-project.yaml

@@ -0,0 +1,13 @@
+schema_version: "1.0"
+identity:
+  name: client-project                  # TODO: customize via --name
+  being: workspace
+  purpose: Client-specific project artifacts and deliverables
+director: false
+tags:
+  - client
+  - project
+  - active
+rules:
+  - Sensitive client data — confirm sharing permissions before external distribution
+  - Archive after project handoff

folder_nature/templates/deployment.yaml

@@ -0,0 +1,14 @@
+schema_version: "1.0"
+identity:
+  name: deployment                      # TODO: customize via --name
+  being: configs
+  purpose: Production-touching configuration and deploy scripts
+director: false
+tags:
+  - production
+  - deploy
+  - sensitive
+rules:
+  - Only deploy scripts and verified-by-review configs live here
+  - Changes require explicit deploy approval; do not edit in-place during incidents
+  - Secrets never stored here in plaintext — use .env or secret manager references

folder_nature/templates/documentation.yaml

@@ -0,0 +1,12 @@
+schema_version: "1.0"
+identity:
+  name: documentation                   # TODO: customize via --name
+  being: documentation
+  purpose: Project documentation, guides, and references
+director: false
+tags:
+  - docs
+  - reference
+rules:
+  - Keep documentation current — update alongside the systems it describes
+  - Markdown preferred for portability

folder_nature/templates/workspace.yaml

@@ -0,0 +1,11 @@
+schema_version: "1.0"
+identity:
+  name: workspace                       # TODO: customize via --name or replace
+  being: workspace
+  purpose: Active working directory for ongoing project work
+director: false
+tags:
+  - work
+  - active
+rules:
+  - Files in this directory are work-in-progress; consider archiving stable artifacts

folder_nature-0.1.0.dist-info/METADATA

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: folder-nature
+Version: 0.1.0
+Summary: Semantic identity for filesystem folders — folders become conversation partners
+Author: Illia Hladkyi
+License: MIT
+Project-URL: Homepage, https://github.com/myfjin/folder-nature
+Project-URL: Repository, https://github.com/myfjin/folder-nature
+Project-URL: Issues, https://github.com/myfjin/folder-nature/issues
+Keywords: filesystem,metadata,semantic,organization,self-hosted
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Dynamic: license-file
+
+# folder-nature
+
+> *Folders are not containers. They're ecosystems with collective memory, personality, and rules.*
+
+A directory becomes a conversation partner: it has identity, purpose, rules,
+and history, all captured in a hidden `.folder-nature` YAML file at the
+directory's root.
+
+## What problem this solves
+
+Filesystems don't carry meaning. `~/Projects/old_v3_final/` could be anything.
+Search-by-filename doesn't help when you can't remember the filename. New team
+members start from zero. AI assistants scan everything.
+
+folder-nature attaches a small piece of YAML to each directory that captures:
+- What this folder is for
+- What kind of folder it is (workspace, archive, configs, ...)
+- What tags apply
+- What rules govern it
+- When it was created and what notable things happened
+
+Once attached, you can search by meaning, walk up to find the boss folder,
+validate the tree, and let AI tools query a folder's intent before they
+interact with its contents.
+
+## Install
+
+```bash
+pip install git+https://github.com/myfjin/folder-nature.git
+```
+
+Requires Python 3.10+. Single runtime dependency: PyYAML.
+
+> **PyPI release planned for late July 2026.** Once published, install
+> will simplify to `pip install folder-nature`.
+
+## 5-minute tour
+
+```bash
+# Create something to tag
+mkdir demo && cd demo
+mkdir -p Old_Stuff RANDOM new_new_final download untitled_folder
+
+# Tag the root
+folder-nature init . --template workspace --name "demo-workspace"
+
+# Show what got created
+folder-nature show .
+
+# Reorganize + tag the new structure
+mkdir -p projects/{active,archive} clients/{acme,startup-x} documents
+folder-nature init projects/active --template workspace
+folder-nature init projects/archive --template archive
+folder-nature init clients --template client-project --name "my-clients"
+folder-nature init documents --template documentation
+
+# Search by meaning
+folder-nature search . --tag client
+folder-nature search . --being collector
+
+# Validate the tree
+folder-nature validate .
+
+# Tree view
+folder-nature list .
+```
+
+## Templates (`init --template`)
+
+Five archetypes ship with the package:
+
+| Template | When to use |
+|----------|-------------|
+| `workspace` | Active project working directory |
+| `client-project` | Client-specific work folder |
+| `archive` | Historical / inactive storage |
+| `deployment` | Production-touching configs and scripts |
+| `documentation` | Docs, references, guides |
+
+Customize at init time with `--name "your-name"` or edit the resulting
+`.folder-nature` file directly afterward.
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `folder-nature init [PATH] [--template T]` | Create a new `.folder-nature` |
+| `folder-nature show [PATH]` | Print closest `.folder-nature` (walks up) |
+| `folder-nature query [PATH]` | Find the `director: true` ancestor |
+| `folder-nature search [ROOT] [--tag T] [--being B] [--name N]` | Filter folders by criteria |
+| `folder-nature validate [ROOT]` | Schema-check all `.folder-nature` files in tree |
+| `folder-nature list [ROOT]` | Tree view of every tagged folder |
+| `folder-nature version` | Print tool + schema versions |
+
+`PATH` and `ROOT` default to the current directory.
+
+## Schema v1.0
+
+A `.folder-nature` file is YAML with this shape:
+
+```yaml
+schema_version: "1.0"             # REQUIRED
+
+identity:                         # REQUIRED
+  name: "Projects"
+  being: "director"
+  purpose: "Canonical root for all work"
+
+director: true                    # OPTIONAL (default false)
+
+tags:                             # OPTIONAL
+  - work
+  - canonical
+  - active
+
+rules:                            # OPTIONAL
+  - "Only deployed code lives here"
+
+memory:                           # OPTIONAL
+  created: "2026-05-09"
+  last_significant_change: "2026-06-22"
+  notable_events:
+    - "2026-05-09: initial setup"
+```
+
+The `identity.being` field accepts a controlled vocabulary plus arbitrary
+custom values (extensibility hatch). Known types:
+
+`director` · `collector` · `workspace` · `assets` · `configs` ·
+`documentation` · `ideas` · `external` · `legal` · `team-shared` ·
+`private` · `system`
+
+## Design principles
+
+1. **Files, not databases.** Each folder owns its own YAML. Git-friendly,
+   editor-friendly, no central store.
+2. **Self-hosted.** Runs entirely local. No network calls. No telemetry.
+3. **Schema-versioned.** Future schema bumps migrate cleanly.
+4. **AI-readable.** Optional integration with LLM assistants — they query the
+   folder's nature before interacting with its contents.
+5. **Open from day one.** MIT licensed. Code reviewable. Schema documented.
+
+## Roadmap
+
+- **v0.1 (this release):** core MVP — schema, CLI, 5 templates, tests
+- **v0.2:** export/import, migration tool, more templates
+- **v1.0:** AI integration (`folder-nature ai-suggest`), filesystem watcher,
+  comprehensive docs
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Development
+
+```bash
+git clone https://github.com/myfjin/folder-nature
+cd folder-nature
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest
+```
+
+Test suite: 66 tests covering schema validation, filesystem operations,
+search, and CLI integration. Should run in <1 second.
+
+## Origin
+
+folder-nature emerged from internal infrastructure work in early 2026 —
+a working hypothesis that filesystems become more useful when directories
+carry semantic identity. The concept proved itself on a 3-node operational
+mesh before being extracted as this standalone tool.
+
+🐍🦅💎

folder_nature-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+folder_nature/__init__.py,sha256=KSrS6U8W83igAbUQhZvDofuzE8nhJDJ3CwbP6Tq8x2k,1184
+folder_nature/cli.py,sha256=dGGH-1ugxEx2OK-qm8l1V19iN7997nq__zpEAmv5Imk,11219
+folder_nature/core.py,sha256=-ZZ-h8oj-AS5wTZyy5X6ZN_19LmzrXYBkPSF2mA1JP8,3758
+folder_nature/schema.py,sha256=ZOAmAWSQL4E7Kdbox64V6Wv3cVKuXFom5UQ5ecSXHjY,9359
+folder_nature/search.py,sha256=HNkvSoKuBVYXAXjm34FUWEWMCUyYCkRtH2ScTLIRJuA,4108
+folder_nature/templates/archive.yaml,sha256=gBSGb-_VepoyULoicfDb-IwyeyjoUUu7r4Vij472OoQ,368
+folder_nature/templates/client-project.yaml,sha256=Vu7OD_6Rjb9USdkPFJoPCnt7NJE138e2ZS-avbJoDvQ,366
+folder_nature/templates/deployment.yaml,sha256=dvHUmI5QLUp_FStOOd7pfy-JVFkOlH2BW024XR2OOTA,485
+folder_nature/templates/documentation.yaml,sha256=C1Y0d86Shlx4FlGFolHDDFFSqerIoAXk92Ru7kDd7So,349
+folder_nature/templates/workspace.yaml,sha256=q8NSoeIh2NwVYWcQ2aXMyT-BHV8zWMbEJCQiHVundT0,327
+folder_nature-0.1.0.dist-info/licenses/LICENSE,sha256=G4GyA00gWQieZa1oMRfToMkhsEhVn5cXpIwfPVMuhu4,1070
+folder_nature-0.1.0.dist-info/METADATA,sha256=SZzvyKoe66JbhNCwLQwqYPkNowZQ84p2rNLMo36j_AE,6708
+folder_nature-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+folder_nature-0.1.0.dist-info/entry_points.txt,sha256=ebYJv1BLDNz13dr5PZjFxl46retMjtblC-ZsmKQlnWQ,57
+folder_nature-0.1.0.dist-info/top_level.txt,sha256=HGXz9UE9DVAnCt7sCkmWeVCvvS_loxTE3A4YyV5m9Ak,14
+folder_nature-0.1.0.dist-info/RECORD,,

folder_nature-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

folder_nature-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+folder-nature = folder_nature.cli:main

folder_nature-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Illia Hladkyi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

folder_nature-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+folder_nature