monag 0.3.0__tar.gz

monag-0.3.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: monag
+Version: 0.3.0
+Summary: See agent processes, concurrent checkouts and recent GitHub workspace activity in your terminal
+Author: semcod
+License-Expression: MIT
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: rich<15,>=14
+Provides-Extra: dev
+Requires-Dist: build<2,>=1; extra == "dev"
+Requires-Dist: twine<7,>=6; extra == "dev"
+Requires-Dist: setuptools>=77.0.3; extra == "dev"
+
+# monag
+
+A terminal view of agents working across your GitHub workspace. Linux, Python
+3.10+, Git; Rich renders Markdown in the terminal. Optional GitHub integration uses `gh`.
+
+```sh
+python3 -m pip install .
+monag
+monag status
+monag --machine --agents-only watch
+monag --machine --agents-only --view tree watch
+monag --root ~/github --markdown status > activity.md
+monag --root ~/github watch
+monag --root ~/github --github status
+monag --root ~/github --json status
+monag history --search ticket-001
+monag doctor
+monag run --task "Fix issue #42" --issue 42 -- claude
+./project.sh --help
+```
+
+Running `monag` in a terminal opens the interactive shell and immediately prints
+the agent dashboard plus the restart/backlog inventory. Use `refresh` to repeat
+both reports, `resume` for worktrees and Planfile tickets, `audit` for the
+Planfile/GitHub comparison, and `quit` or Ctrl-D to exit. `monag watch` remains
+available for an always-refreshing dashboard; Ctrl-C exits it.
+Use `monag status` for one snapshot. Pipes, `--json`, and `--markdown` default
+to one snapshot unless `watch` is explicit.
+
+Shows agent process count, working directories, concurrent agents in a checkout,
+process trees and their working directories, changed files, recent commits,
+reported tasks, searchable local history, and optional GitHub issues/PRs.
+Custom agents: `--agent LABEL=EXECUTABLE` or `run --agent-kind LABEL`.
+Open descriptor paths: `--open-files`. Watch records observations by default;
+use `watch --no-record` to disable recording.
+Put global options before `status`, `watch`, or `run`.
+
+Planfile tickets are stored per sprint. `planfile ticket list` shows only the
+`current` sprint; inspect the backlog explicitly with `planfile ticket list
+--sprint backlog` (or use `monag resume`, which reads every local sprint and
+legacy keyed records). To reconcile local tickets with GitHub, run the
+read-only preview first:
+
+```sh
+planfile sync github --dry-run --direction both
+planfile sync github --direction both
+```
+
+[Usage, interpretation and limitations](docs/information/usage.md) ·
+[Documentation](docs/README.md)
+
+Governance checks are available through `./project.sh` on Linux/macOS and
+`project.bat` on Windows; both entry points execute the repository's pinned
+governance validator before optional analysis tooling.

monag-0.3.0/README.md

@@ -0,0 +1,54 @@
+# monag
+
+A terminal view of agents working across your GitHub workspace. Linux, Python
+3.10+, Git; Rich renders Markdown in the terminal. Optional GitHub integration uses `gh`.
+
+```sh
+python3 -m pip install .
+monag
+monag status
+monag --machine --agents-only watch
+monag --machine --agents-only --view tree watch
+monag --root ~/github --markdown status > activity.md
+monag --root ~/github watch
+monag --root ~/github --github status
+monag --root ~/github --json status
+monag history --search ticket-001
+monag doctor
+monag run --task "Fix issue #42" --issue 42 -- claude
+./project.sh --help
+```
+
+Running `monag` in a terminal opens the interactive shell and immediately prints
+the agent dashboard plus the restart/backlog inventory. Use `refresh` to repeat
+both reports, `resume` for worktrees and Planfile tickets, `audit` for the
+Planfile/GitHub comparison, and `quit` or Ctrl-D to exit. `monag watch` remains
+available for an always-refreshing dashboard; Ctrl-C exits it.
+Use `monag status` for one snapshot. Pipes, `--json`, and `--markdown` default
+to one snapshot unless `watch` is explicit.
+
+Shows agent process count, working directories, concurrent agents in a checkout,
+process trees and their working directories, changed files, recent commits,
+reported tasks, searchable local history, and optional GitHub issues/PRs.
+Custom agents: `--agent LABEL=EXECUTABLE` or `run --agent-kind LABEL`.
+Open descriptor paths: `--open-files`. Watch records observations by default;
+use `watch --no-record` to disable recording.
+Put global options before `status`, `watch`, or `run`.
+
+Planfile tickets are stored per sprint. `planfile ticket list` shows only the
+`current` sprint; inspect the backlog explicitly with `planfile ticket list
+--sprint backlog` (or use `monag resume`, which reads every local sprint and
+legacy keyed records). To reconcile local tickets with GitHub, run the
+read-only preview first:
+
+```sh
+planfile sync github --dry-run --direction both
+planfile sync github --direction both
+```
+
+[Usage, interpretation and limitations](docs/information/usage.md) ·
+[Documentation](docs/README.md)
+
+Governance checks are available through `./project.sh` on Linux/macOS and
+`project.bat` on Windows; both entry points execute the repository's pinned
+governance validator before optional analysis tooling.

monag-0.3.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "monag"
+version = "0.3.0"
+description = "See agent processes, concurrent checkouts and recent GitHub workspace activity in your terminal"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{name = "semcod"}]
+classifiers = ["Environment :: Console", "Operating System :: POSIX :: Linux", "Programming Language :: Python :: 3"]
+dependencies = ["rich>=14,<15"]
+
+[project.optional-dependencies]
+dev = ["build>=1,<2", "twine>=6,<7", "setuptools>=77.0.3"]
+
+[project.scripts]
+monag = "monag.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.wellmanifest]
+standard = "0.20.31"
+revision = "2b016654cff1a1ccef2c0d6126a9c2550ae6b37a"
+gate = "project/governance-check.sh"
+
+[tool.pytest.ini_options]
+addopts = "-p wellmanifest_governance"
+pythonpath = ["src", "tests"]

monag-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

monag-0.3.0/src/monag/__init__.py

@@ -0,0 +1,2 @@
+"""Agent activity monitor."""
+__version__ = "0.3.0"

monag-0.3.0/src/monag/__main__.py

@@ -0,0 +1,2 @@
+from .cli import main
+raise SystemExit(main())

monag-0.3.0/src/monag/agents.py

@@ -0,0 +1,59 @@
+"""Extensible executable detection; never search prompts or arbitrary arguments."""
+from pathlib import Path
+import re
+
+ALIASES = {name: name for name in (
+    'codex', 'claude', 'aider', 'gemini', 'opencode', 'goose', 'cursor-agent',
+    'amp', 'qwen', 'kilo', 'copilot', 'crush', 'openhands', 'continue', 'devin',
+)}
+MODULES = {'aider': 'aider', 'aider.main': 'aider', 'openhands': 'openhands'}
+SCOPES = {'@openai/codex': 'codex', '@anthropic-ai/claude-code': 'claude',
+          '@google/gemini-cli': 'gemini', '@qwen-code/qwen-code': 'qwen',
+          '@github/copilot': 'copilot'}
+# Agent Client Protocol adapters started by IDEs, e.g. claude-agent-acp or glm-acp-agent.
+ACP = re.compile(r'[a-z0-9][a-z0-9_.-]*-(?:agent-acp|acp-agent|acp)')
+# Helper modes selected by a leading flag are not agent sessions.
+HELPER_FLAGS = {'--chrome-native-host'}
+
+
+def aliases(entries=()):
+    result = dict(ALIASES)
+    for entry in entries:
+        kind, sep, executable = entry.partition('=')
+        if not sep or not re.fullmatch(r'[a-zA-Z0-9_-]+', kind) or not executable or Path(executable).name != executable:
+            raise ValueError('--agent must be LABEL=EXECUTABLE (a basename, without a path)')
+        result[executable] = kind
+    return result
+
+
+def kind_of(name, registry):
+    return registry.get(name) or (name if ACP.fullmatch(name) else None)
+
+
+def helper(arguments):
+    # Only an exact leading flag is compared; a positional prompt is never read.
+    return bool(arguments) and arguments[0] in HELPER_FLAGS
+
+
+def identify(argv, registry=None):
+    registry = ALIASES if registry is None else registry
+    if not argv or not argv[0]:
+        return None, False
+    executable = Path(argv[0]).name
+    kind = kind_of(executable, registry)
+    if kind:
+        return (None, False) if helper(argv[1:]) else (kind, False)
+    runtime = executable in {'node', 'nodejs', 'bun', 'deno'} or re.fullmatch(r'python(?:\d+(?:\.\d+)*)?', executable)
+    if not runtime or len(argv) < 2:
+        return None, False
+    if argv[1] == '-m' and len(argv) > 2:
+        return MODULES.get(argv[2], registry.get(argv[2])), True
+    # Only the runtime's entrypoint is inspected, never trailing arguments.
+    script = argv[1]
+    if script.startswith('-'):
+        return None, False
+    name = Path(script).name.removesuffix('.js').removesuffix('.mjs').removesuffix('.py')
+    kind = kind_of(name, registry) or next((k for scope, k in SCOPES.items() if f'/{scope}/' in script), None)
+    if not kind or helper(argv[2:]):
+        return None, False
+    return kind, True

monag-0.3.0/src/monag/audit.py

@@ -0,0 +1,189 @@
+"""Read-only audit of local Planfile ticket coverage against GitHub Issues.
+
+For one repository (`--root` is a Git checkout) this reports how many of its
+GitHub Issues have a corresponding Planfile ticket, which tickets have none,
+and whether a ticket's own GitHub mapping agrees with the repository-wide
+sync index (`.planfile/sync/github.state.yaml`). When `--root` is a workspace
+of several repositories (not itself a checkout, e.g. the default `~/github`),
+the same audit runs for every discovered repository with a GitHub remote.
+
+`gh` failures, a missing remote, or a repository without a local Planfile are
+all reported as explicit unknowns, never silently treated as "zero".
+"""
+from concurrent.futures import ThreadPoolExecutor
+from datetime import datetime, timezone
+import json
+from pathlib import Path
+import time
+
+import yaml
+
+from .monitor import command, github_repo
+from .presentation import table
+from .resume import planfile as read_planfile, registrations, roots as discover_roots
+
+SCHEMA = 'monag.audit/v1'
+
+
+def sync_index(path):
+    """The repository-wide Planfile-to-GitHub mapping, if one is recorded."""
+    file = Path(path) / '.planfile' / 'sync' / 'github.state.yaml'
+    if not file.is_file():
+        return {}, None, None
+    try:
+        if file.stat().st_size > 2_000_000:
+            raise ValueError('file exceeds 2 MB read limit')
+        data = yaml.load(file.read_text(), Loader=getattr(yaml, 'CSafeLoader', yaml.SafeLoader))
+        mapping = data.get('ticket_map') if isinstance(data, dict) else None
+        if not isinstance(mapping, dict):
+            raise ValueError('expected a ticket_map mapping')
+        return ({str(k): str(v) for k, v in mapping.items() if v is not None},
+                str(file), None)
+    except (OSError, ValueError, TypeError, yaml.YAMLError, RecursionError) as error:
+        return {}, str(file), f'{file}: {type(error).__name__}'
+
+
+def repo_remote(path):
+    remote, _ = command(['git', 'config', '--get', 'remote.origin.url'], path)
+    return github_repo(remote) if remote else None
+
+
+def github_issues(repo, limit=200):
+    """All GitHub Issues (open and closed) for a repository, via `gh`."""
+    out, error = command(['gh', 'issue', 'list', '--repo', repo, '--state', 'all',
+                          '--limit', str(limit), '--json',
+                          'number,title,state,url,updatedAt,labels'], timeout=20)
+    if error:
+        return None, [f'{repo}: {error}']
+    try:
+        issues = json.loads(out)
+        if not isinstance(issues, list):
+            raise ValueError('expected a JSON array')
+        return issues, []
+    except (ValueError, TypeError):
+        return None, [f'{repo}: invalid gh JSON']
+
+
+def audit_repo(path, issue_limit=200):
+    """One repository's coverage report; never raises, errors are data."""
+    path = Path(path)
+    tickets, planfile_sources, planfile_errors = read_planfile(path)
+    index, index_source, index_error = sync_index(path)
+    repo = repo_remote(path)
+    issues, github_errors = (None, []) if repo is None else github_issues(repo, issue_limit)
+    fetched = repo is not None and not github_errors
+    issues = issues or []
+    issue_by_number = {str(item['number']): item for item in issues
+                       if isinstance(item, dict) and 'number' in item}
+    mapped = {t['id']: t['github'] for t in tickets if t.get('github')}
+    tracked_numbers = set(mapped.values())
+    untracked_issues = ([item for item in issues
+                         if str(item.get('number')) not in tracked_numbers] if fetched else [])
+    orphan_tickets = ([{'id': ticket_id, 'github': issue_id} for ticket_id, issue_id in mapped.items()
+                       if issue_id not in issue_by_number] if fetched else [])
+    # Meaningful only once a sync index file exists: its absence is a different,
+    # unrelated fact from an existing index missing one ticket's entry.
+    sync_drift = ([{'id': ticket_id, 'github': issue_id, 'in_sync_index': index.get(ticket_id) == issue_id}
+                  for ticket_id, issue_id in sorted(mapped.items()) if index.get(ticket_id) != issue_id]
+                 if index_source is not None else [])
+    return {
+        'path': str(path), 'repo': repo,
+        'planfile_available': bool(planfile_sources),
+        'planfile_sources': planfile_sources, 'planfile_errors': planfile_errors,
+        'tickets': tickets, 'ticket_count': len(tickets), 'mapped_ticket_count': len(mapped),
+        'sync_index_source': index_source, 'sync_index_error': index_error,
+        'github_fetched': fetched, 'github_errors': github_errors,
+        'github_issue_count': len(issues) if fetched else None,
+        'github_open': sum(1 for i in issues if i.get('state') == 'OPEN') if fetched else None,
+        'github_closed': sum(1 for i in issues if i.get('state') == 'CLOSED') if fetched else None,
+        'untracked_issues': untracked_issues, 'orphan_tickets': orphan_tickets,
+        'sync_drift': sync_drift,
+    }
+
+
+def targets(root, depth):
+    """(mode, [primary checkout paths]) — one repository, or every one under root."""
+    root = Path(root)
+    if (root / '.git').exists():
+        records, error = registrations(root)
+        primary = Path(records[0]['path']) if records and not error else root
+        return 'repository', [primary], ([f'{root}: {error}'] if error else [])
+    found, seen, errors = [], set(), []
+    for candidate in discover_roots(root, depth):
+        records, error = registrations(candidate)
+        if error or not records:
+            errors.append(f'{candidate}: {error or "no worktree records"}')
+            continue
+        primary = Path(records[0]['path'])
+        if str(primary) in seen:
+            continue
+        seen.add(str(primary))
+        found.append(primary)
+    return 'workspace', found, errors
+
+
+def scan(root, depth=2, issue_limit=200):
+    started = time.monotonic()
+    mode, paths, errors = targets(root, depth)
+    with ThreadPoolExecutor(max_workers=8) as pool:
+        repositories = list(pool.map(lambda p: audit_repo(p, issue_limit), paths))
+    repositories.sort(key=lambda r: (-len(r['untracked_issues']), -len(r['sync_drift']),
+                                     -len(r['orphan_tickets']), r['path']))
+    return {
+        'schema': SCHEMA, 'root': str(root), 'mode': mode,
+        'observed_at': datetime.now(timezone.utc).isoformat(),
+        'duration_seconds': round(time.monotonic() - started, 2),
+        'repositories': repositories, 'repository_count': len(repositories),
+        'repositories_with_github': sum(1 for r in repositories if r['repo']),
+        'repositories_with_planfile': sum(1 for r in repositories if r['planfile_available']),
+        'total_github_issues': sum(r['github_issue_count'] or 0 for r in repositories),
+        'total_planfile_tickets': sum(r['ticket_count'] for r in repositories),
+        'total_untracked_issues': sum(len(r['untracked_issues']) for r in repositories),
+        'total_sync_drift': sum(len(r['sync_drift']) for r in repositories),
+        'errors': errors,
+        'notice': 'Read-only comparison of local Planfile tickets against GitHub Issues via `gh`; '
+                  'no writes to either. A missing GitHub remote or failed `gh` call leaves that '
+                  'repository\'s issue counts unset (shown as "-"), never zero. Sync-index drift '
+                  'compares a ticket\'s own mapping against .planfile/sync/github.state.yaml; a '
+                  'missing global entry does not mean the ticket itself is wrong.',
+    }
+
+
+def markdown(data, limit=12):
+    lines = ['# MONAG — Planfile / GitHub coverage audit', '',
+             f"Mode: **{data['mode']}** · repositories: **{data['repository_count']}** "
+             f"({data['repositories_with_github']} with a GitHub remote, "
+             f"{data['repositories_with_planfile']} with a local Planfile) · scan: "
+             f"{data['duration_seconds']} s.", '',
+             f"GitHub issues observed: **{data['total_github_issues']}** · "
+             f"Planfile tickets: **{data['total_planfile_tickets']}** · "
+             f"issues with no Planfile ticket: **{data['total_untracked_issues']}** · "
+             f"ticket/sync-index drift: **{data['total_sync_drift']}**.", '',
+             '## Repositories', '']
+    shown = data['repositories'][:limit]
+    lines.append(table(['Repository', 'GitHub issues', 'Planfile tickets', 'Mapped', 'Untracked', 'Orphan', 'Sync drift'],
+                       [[r['repo'] or r['path'],
+                         r['github_issue_count'] if r['github_issue_count'] is not None else '-',
+                         r['ticket_count'] if r['planfile_available'] else '-',
+                         r['mapped_ticket_count'], len(r['untracked_issues']),
+                         len(r['orphan_tickets']), len(r['sync_drift'])] for r in shown]))
+    untracked_rows = [[r['repo'] or r['path'], '#' + str(issue.get('number')),
+                       issue.get('state', ''), issue.get('title', '')]
+                      for r in shown for issue in r['untracked_issues'][:limit]]
+    lines.extend(['', '## GitHub issues with no Planfile ticket', '',
+                 table(['Repository', 'Issue', 'State', 'Title'], untracked_rows[:limit])])
+    drift_rows = [[r['repo'] or r['path'], drift['id'], drift['github'],
+                  'present' if drift['in_sync_index'] else 'missing/mismatched']
+                 for r in shown for drift in r['sync_drift'][:limit]]
+    lines.extend(['', '## Ticket vs. sync-index drift', '',
+                 table(['Repository', 'Ticket', 'GitHub id', 'Global sync index'], drift_rows[:limit])])
+    orphan_rows = [[r['repo'] or r['path'], orphan['id'], orphan['github']]
+                  for r in shown for orphan in r['orphan_tickets'][:limit]]
+    if orphan_rows:
+        lines.extend(['', '## Planfile tickets mapped to a missing GitHub issue', '',
+                     table(['Repository', 'Ticket', 'GitHub id'], orphan_rows[:limit])])
+    failures = (data['errors'] + [e for r in data['repositories'] for e in r['planfile_errors']] +
+               [e for r in data['repositories'] for e in r['github_errors']])
+    lines.extend(['', f"Read errors: {len(failures)}. Repositories shown: {min(limit, data['repository_count'])}/{data['repository_count']}.",
+                 '', data['notice'], '', 'Full data and every row: `monag --json audit`.'])
+    return '\n'.join(lines) + '\n'

monag-0.3.0/src/monag/catalog.py

@@ -0,0 +1,192 @@
+"""Read-only catalog of local repositories: what each one is, from its own metadata.
+
+No network calls and no LLM summarization: every field is either read verbatim
+from a manifest or doc the project already ships (pyproject.toml, package.json,
+README.md, ...) or a boolean/timestamp observed directly from the checkout. A
+project with no declared description is reported as unknown, never guessed --
+this is an index of what projects say about themselves, not an opinion.
+"""
+from concurrent.futures import ThreadPoolExecutor
+from datetime import datetime, timezone
+from pathlib import Path
+import json
+import re
+import time
+
+from .audit import targets as discover_targets
+from .monitor import command, github_repo
+from .presentation import table
+
+SCHEMA = 'monag.catalog/v1'
+
+STACK_MANIFESTS = {
+    'python': ('pyproject.toml', 'setup.py', 'setup.cfg', 'requirements.txt'),
+    'node': ('package.json',),
+    'go': ('go.mod',),
+    'rust': ('Cargo.toml',),
+    'java': ('pom.xml', 'build.gradle', 'build.gradle.kts'),
+    'docker': ('Dockerfile', 'docker-compose.yml', 'docker-compose.yaml'),
+}
+
+
+def detect_stacks(path):
+    return sorted(name for name, files in STACK_MANIFESTS.items()
+                 if any((path / name_file).is_file() for name_file in files))
+
+
+def read_text(path, limit=200_000):
+    try:
+        if not path.is_file() or path.is_symlink() or path.stat().st_size > limit:
+            return None
+        return path.read_text(errors='replace')
+    except OSError:
+        return None
+
+
+def description_from_pyproject(path):
+    text = read_text(path / 'pyproject.toml')
+    if not text:
+        return None
+    match = re.search(r'(?m)^\s*description\s*=\s*"((?:[^"\\]|\\.)*)"', text)
+    if not match:
+        return None
+    value = match.group(1).replace('\\"', '"').strip()
+    return value or None
+
+
+def description_from_package_json(path):
+    text = read_text(path / 'package.json')
+    if not text:
+        return None
+    try:
+        data = json.loads(text)
+    except ValueError:
+        return None
+    value = data.get('description') if isinstance(data, dict) else None
+    return value.strip() if isinstance(value, str) and value.strip() else None
+
+
+def description_from_readme(path):
+    for name in ('README.md', 'README.rst', 'README.txt', 'README'):
+        text = read_text(path / name)
+        if not text:
+            continue
+        paragraph = []
+        for line in text.splitlines():
+            stripped = line.strip()
+            if not stripped:
+                if paragraph:
+                    break
+                continue
+            if stripped.startswith(('#', '```', '![', '|', '<', '[!', '>')):
+                continue
+            paragraph.append(stripped)
+        if paragraph:
+            return ' '.join(paragraph)[:400]
+    return None
+
+
+DESCRIPTION_SOURCES = (
+    (description_from_pyproject, 'pyproject.toml'),
+    (description_from_package_json, 'package.json'),
+    (description_from_readme, 'README.md'),
+)
+
+
+def entry_points(path):
+    points = set()
+    pyproject = read_text(path / 'pyproject.toml')
+    if pyproject:
+        section = re.search(r'(?ms)^\[project\.scripts\]\s*$(.*?)(?=^\[|\Z)', pyproject)
+        if section:
+            points.update(re.findall(r'(?m)^\s*([A-Za-z0-9_.-]+)\s*=', section.group(1)))
+    package_json = read_text(path / 'package.json')
+    if package_json:
+        try:
+            data = json.loads(package_json)
+        except ValueError:
+            data = None
+        if isinstance(data, dict):
+            bin_field = data.get('bin')
+            if isinstance(bin_field, dict):
+                points.update(k for k in bin_field if isinstance(k, str))
+            elif isinstance(bin_field, str) and isinstance(data.get('name'), str):
+                points.add(data['name'])
+    return sorted(points)
+
+
+def last_commit(path):
+    out, error = command(['git', 'log', '-1', '--format=%ct%x00%s'], path)
+    if error or not out.strip():
+        return None, None
+    stamp, _, subject = out.strip('\n').partition('\0')
+    try:
+        when = datetime.fromtimestamp(int(stamp), timezone.utc).isoformat()
+    except (ValueError, OverflowError):
+        return None, subject or None
+    return when, subject or None
+
+
+def describe_repo(path):
+    """One repository's self-declared identity; never raises, errors are data."""
+    path = Path(path)
+    remote, _ = command(['git', 'config', '--get', 'remote.origin.url'], path)
+    repo = github_repo(remote) if remote else None
+    description, source = None, None
+    for extractor, label in DESCRIPTION_SOURCES:
+        description = extractor(path)
+        if description:
+            source = label
+            break
+    commit_at, commit_subject = last_commit(path)
+    return {
+        'path': str(path), 'name': path.name, 'repo': repo,
+        'description': description, 'description_source': source,
+        'stacks': detect_stacks(path), 'entry_points': entry_points(path),
+        'has_docs': (path / 'docs').is_dir(),
+        'has_tests': any((path / name).is_dir() for name in ('tests', 'test')),
+        'has_changelog': (path / 'CHANGELOG.md').is_file(),
+        'last_commit_at': commit_at, 'last_commit_subject': commit_subject,
+    }
+
+
+def scan(root, depth=2):
+    started = time.monotonic()
+    mode, paths, errors = discover_targets(root, depth)
+    with ThreadPoolExecutor(max_workers=8) as pool:
+        repositories = list(pool.map(describe_repo, paths))
+    repositories.sort(key=lambda r: r['name'])
+    return {
+        'schema': SCHEMA, 'root': str(root), 'mode': mode,
+        'observed_at': datetime.now(timezone.utc).isoformat(),
+        'duration_seconds': round(time.monotonic() - started, 2),
+        'repositories': repositories, 'repository_count': len(repositories),
+        'described_count': sum(1 for r in repositories if r['description']),
+        'undescribed_count': sum(1 for r in repositories if not r['description']),
+        'errors': errors,
+        'notice': 'Read-only, local-only catalog: every field is read verbatim from a '
+                  "manifest or doc the project already ships, or observed directly from "
+                  'the checkout. No network calls, no LLM summarization, no guessing -- '
+                  'a project with no declared description is reported as unknown, not '
+                  'invented.',
+    }
+
+
+def markdown(data, limit=40):
+    lines = ['# MONAG — project catalog', '',
+             f"Mode: **{data['mode']}** · repositories: **{data['repository_count']}** "
+             f"({data['described_count']} with a declared description, "
+             f"{data['undescribed_count']} unknown) · scan: {data['duration_seconds']} s.",
+             '', '## Repositories', '']
+    shown = data['repositories'][:limit]
+    lines.append(table(['Name', 'Stacks', 'Description', 'Docs', 'Tests', 'Last commit'],
+                       [[r['name'], ', '.join(r['stacks']) or '-',
+                         r['description'] or '(undeclared)',
+                         'yes' if r['has_docs'] else 'no', 'yes' if r['has_tests'] else 'no',
+                         (r['last_commit_at'] or '-')[:10]] for r in shown]))
+    undescribed = sorted(r['name'] for r in data['repositories'] if not r['description'])
+    if undescribed:
+        lines.extend(['', '## No declared description', '', ', '.join(undescribed[:limit])])
+    lines.extend(['', f"Repositories shown: {min(limit, data['repository_count'])}/{data['repository_count']}.",
+                 '', data['notice'], '', 'Full data and every row: `monag --json catalog`.'])
+    return '\n'.join(lines) + '\n'