docs: add agent guidance and issue forms

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,95 @@
+name: Bug report
+description: Something went wrong while running theHarvester
+title: "[Bug]: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a problem. The details below help us reproduce and diagnose it.
+
+        Before posting, remove credentials, API keys, account details, and private reconnaissance data. Replace private domains or IP addresses with `example.com` or `192.0.2.1` whenever possible.
+
+  - type: textarea
+    id: actual-behavior
+    attributes:
+      label: What happened?
+      description: Describe the problem and include the error message if one appeared.
+    validations:
+      required: true
+
+  - type: textarea
+    id: command
+    attributes:
+      label: Command you ran
+      description: Paste the exact command, replacing any private domain or IP address with `example.com` or `192.0.2.1` and removing credentials.
+      placeholder: "uv run theHarvester -d example.com -b certspotter"
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: What did you expect to happen?
+      description: Describe the result you expected instead.
+    validations:
+      required: true
+
+  - type: dropdown
+    id: installation-method
+    attributes:
+      label: How did you install theHarvester?
+      description: Android installations are not supported. See the [installation guide](https://github.com/laramies/theHarvester/wiki/Installation) for supported options.
+      options:
+        - Source checkout with uv
+        - pipx
+        - Docker
+        - Operating-system package
+        - Other or not sure
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: theHarvester version
+      description: Copy the version shown in the startup banner. If you run from source, a commit hash is helpful but optional.
+      placeholder: "Example: 4.11.1"
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Add your operating system and Python version. Find the OS version in Windows Settings, About This Mac, or `/etc/os-release` on Linux. Use `python --version`, `pipx list`, or `uv run python --version` as appropriate.
+      placeholder: |
+        Operating system: Ubuntu 24.04
+        Python version: 3.13.5
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Error output or screenshot
+      description: Add only the output needed to diagnose the problem. Redact credentials, real targets, account details, and any sensitive or unrelated data from API responses.
+
+  - type: dropdown
+    id: regression
+    attributes:
+      label: Did this work before?
+      options:
+        - "Yes"
+        - "No"
+        - Unknown
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Submission checks
+      options:
+        - label: I searched existing issues for the same problem.
+          required: true
+        - label: I removed credentials, account details, private targets, and other sensitive data from this report.
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Installation documentation
+    url: https://github.com/laramies/theHarvester/wiki/Installation
+    about: Review supported installation methods and setup instructions before reporting an issue.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,69 @@
+name: Feature request
+description: Propose an operator-facing improvement to theHarvester
+title: "[Feature]: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Describe the operator problem before proposing an implementation. Do not include credentials, private reconnaissance data, or real targets.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Operator problem
+      description: What is difficult or impossible today, and who would benefit from changing it?
+    validations:
+      required: true
+
+  - type: textarea
+    id: outcome
+    attributes:
+      label: Desired outcome
+      description: Describe the behavior an operator should be able to observe.
+    validations:
+      required: true
+
+  - type: dropdown
+    id: affected-areas
+    attributes:
+      label: Affected areas
+      description: Select every surface the request is expected to change.
+      multiple: true
+      options:
+        - CLI
+        - REST API
+        - Discovery source
+        - DNS or active processing
+        - Output or export
+        - Installation or documentation
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed-behavior
+    attributes:
+      label: Proposed behavior
+      description: Explain your preferred behavior without requiring a particular implementation.
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Describe any workarounds or other approaches you considered.
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional context
+      description: Add sanitized examples, mockups, or related issues when useful.
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Submission checks
+      options:
+        - label: I searched existing issues for the same request.
+          required: true
+        - label: I removed credentials, private data, and real targets from this request.
+          required: true

.github/ISSUE_TEMPLATE/issue-template.md

@@ -1,34 +0,0 @@
----
-name: Issue Template
-about: A template for new issues.
-title: "[Bug|Feature Request|Other] Short Description of Issue"
-labels: ''
-
----
-
-## Note we do not support installing theHarvester on android
-
-**Feature Request or Bug or Another**
-Feature Request | Bug | Other
-
-**Describe the feature request or bug or other**
-A clear and concise description of what the bug, feature request,
-or other request is.
-
-**To Reproduce**
-Steps to reproduce the behaviour:
-1. Run tool like this: '...'
-2. See error
-
-**Expected behaviour**
-A clear and concise description of what you expected to happen.
-
-**Screenshots**
-If possible please add screenshots to help explain your problem.
-
-**System Information (System that tool is running on):**
- - OS: [e.g. Windows10]
- - Version [e.g. 2.7]
-
-**Additional context**
-Add any other context about the problem here.

AGENTS.md

@@ -0,0 +1,26 @@
+# Agent guidance
+
+theHarvester is a Python OSINT reconnaissance tool for collecting public information about domains, IPs, emails, names, and related assets.
+
+## Essentials
+
+- The project requires Python 3.12 or newer and uses `uv` for environments and commands.
+- Install development dependencies with `uv sync --all-groups`.
+- For code changes, follow [README/CONTRIBUTING.md](README/CONTRIBUTING.md).
+- Make the smallest requested change, reuse existing code, and preserve unrelated worktree changes.
+- Keep security-sensitive behavior fail-closed. Use mocks or local fixtures for routine verification; run live reconnaissance only in an intentionally configured integration check against an explicitly authorized target.
+- Do not commit credentials, real target or operator data, reconnaissance results, or unsanitized provider payloads. Use RFC-reserved domains and TEST-NET IP ranges in tests and examples.
+
+## Domain language
+
+Read [CONTEXT.md](CONTEXT.md) when changing discovery terminology, evidence classification, scope handling, DNS validation, or P0/P1/P2 activity boundaries.
+
+## Verification
+
+- Focused tests: `uv run pytest <test-path>`
+- Full tests: `uv run pytest`
+- Lint: `uv run ruff check .`
+- Formatting: `uv run ruff format --check .`
+- Typing: `uv run mypy theHarvester`
+
+Run focused checks first and expand according to risk. Report any skipped check and its reason.

CONTEXT.md

@@ -0,0 +1,87 @@
+# theHarvester discovery context
+
+This glossary is the source of truth for discussing subdomain discovery across code, issues, pull requests, output, and documentation. It separates current addressability from historical, indirect, or unresolved evidence.
+
+The definitions state intended semantics; they do not imply that every discovery adapter already produces every evidence class. Update this glossary when a change alters a term's meaning or boundary.
+
+## Language
+
+**Currently addressable subdomain**:
+A normalized, in-scope subdomain with current resolver consensus evidence of an A or AAAA record, or a permitted CNAME chain ending in one, that is neither wildcard-indistinguishable nor resolver-disputed.
+_Avoid_: Valid subdomain, live host, resolved host
+
+**Secondary subdomain evidence**:
+An in-scope DNS-existing, historical, dangling-alias, or indeterminate name observation retained for defensive and investigative use but excluded from the primary currently addressable yield count.
+_Avoid_: Invalid subdomain, dead host, false positive
+
+**Synthetic wildcard-control probe**:
+An in-scope DNS query for a fresh, high-entropy nonce label that is overwhelmingly unlikely to be an exact node, used at an applicable closest-encloser depth to learn the wildcard response distribution. Its answer is validation evidence, never a discovered subdomain.
+_Avoid_: Random wildcard control, random name, test subdomain
+
+**Resolver consensus**:
+The configured agreement among normalized answers from operator-approved resolver vantages within one validation window. It is evidence for current addressability, not proof that a service is reachable or useful.
+_Avoid_: Resolved, DNS success, live
+
+**Wildcard-indistinguishable**:
+An in-scope candidate whose normalized DNS response cannot be distinguished from the learned wildcard response distribution at the applicable closest-encloser depth. It remains secondary subdomain evidence unless later observations distinguish it.
+_Avoid_: Wildcard hit, false positive, invalid host
+
+**Resolver-disputed**:
+An in-scope candidate whose operator-approved resolver vantages do not reach resolver consensus sufficient to classify it as a currently addressable subdomain within one validation window. It remains secondary subdomain evidence until later observations resolve the disagreement.
+_Avoid_: Invalid, dead, DNS failure
+
+**In-scope candidate**:
+A normalized name inside an explicitly authorized target boundary that has discovery evidence but has not yet met the currently addressable subdomain criteria. It remains secondary subdomain evidence until those criteria are met.
+_Avoid_: Unverified host, maybe-valid subdomain
+
+**Scope-extension candidate**:
+An entity outside the current authorized boundary with evidence suggesting possible organizational relevance. It may be presented for operator review but cannot be actively queried, counted as a target result, or used for recursive discovery unless explicitly added to scope.
+_Avoid_: Potentially in scope, related subdomain, unverified subdomain
+
+**External relationship evidence**:
+An out-of-scope entity referenced by an in-scope observation, such as an external CNAME target or shared service. It is retained as context rather than treated as a target result or discovery seed.
+_Avoid_: Related subdomain, discovered asset
+
+**Discovery observation**:
+One source assertion about one normalized entity during one enumeration run. Several observations may support the same merged result, and deduplication never erases them.
+_Avoid_: Result, duplicate, hit
+
+**Merged result**:
+A deduplicated operator-facing entity backed by one or more discovery observations and their retained provenance.
+_Avoid_: Raw finding, source result
+
+**DNS validation observation**:
+One resolver vantage's time-bound DNS evidence about one in-scope candidate. It supports classifying the candidate as currently addressable or wildcard-indistinguishable without replacing its discovery observations.
+_Avoid_: DNS result, resolved host, validation status
+
+**Enumeration run**:
+One finite execution of theHarvester against an explicit target and selected options, identified independently from every other execution.
+_Avoid_: Scan, monitoring cycle, session
+
+**Source execution**:
+One attempt to run one canonical discovery source within an enumeration run, with an explicit completion status and summary counts.
+_Avoid_: Source result, provider response
+
+**Source family**:
+A group of discovery sources whose observations depend on the same underlying dataset or collection mechanism. Family membership preserves source credit while preventing correlated observations from being treated as independent corroboration.
+_Avoid_: Duplicate source, provider category
+
+**Normalized evidence**:
+Provider-independent evidence extracted into theHarvester's defined fields, such as the entity, source, collection time, and derivation, without retaining unrelated response content.
+_Avoid_: Raw result, cleaned response
+
+**Raw provider payload**:
+The original unprocessed response returned by a discovery provider, which may contain unused, sensitive, or redistribution-restricted fields.
+_Avoid_: Evidence record, JSONL result
+
+**P0 passive collection**:
+An activity that queries an existing provider or dataset without directing traffic toward the target.
+_Avoid_: Passive scan
+
+**P1 DNS interaction**:
+An activity that queries DNS about the target or its authorized scope, including resolution, wildcard controls, brute force, PTR, and recursive DNS discovery.
+_Avoid_: Passive collection, harmless lookup
+
+**P2 direct interaction**:
+An activity that contacts or scans the target directly or causes a provider to do so, including HTTP or TLS requests, screenshots, takeover checks, and port or endpoint scanning.
+_Avoid_: Deep scan, comprehensive mode